Question

In case of lack of proper updated tutorials for some particular library functions (in my case, latest allegro5), how can one learn by oneself how to call and use those functions? Is there some clue in header files?

thanks in advance

Answer 1

The header files are going to provide you with the bare minimum information required to correctly compile a program with those functions. It has the types, constants, and function prototypes. Nothing (short of comments) is going to explain how to correctly use the functions, just how to call them.

General

For example, if you see:

int do_something(int n, const char* desc);

You can only infer that you need to pass an integer n and a (C) string desc. That function returns an integer as well.

For a more complex example:

typedef struct {
    int foo;
    double bar;
} blam_t;

void munge(blam_t info);

You know that munge takes one argument of type blam_t which is a custom structure, as defined above. You could use that to create a blam_t variable and pass it to munge():

blam_t myvar;
myvar.foo = 42;
myvar.bar = 0.67;

munge(myar);

Allegro5

If we look at the source of include/allegro5/display.h we see things like this:

AL_FUNC(void, al_set_new_display_flags, (int flags));

This is an uncommon way of defining functions. They are using a macro AL_FUNC to define their functions. We see (by clicking on it) that AL_FUNC is defined as:

#define AL_FUNC(type, name, args)               type name args

So that first example basically becomes:

void al_set_new_display_flags(int flags);

And we can call it with just an integer argument.

Without any documentation, you can only hope to learn by trying the functions. Then this becomes more a reverse engineering task.