Question

After having some readings about Doxygen I’m a bit confused where to document my variable, function etc. Should it be in the implementation file(source) or in its interface(header file).

What is the best practise regarding that.

Answer 1

Place documentation in your headers. And one very important thing to look out for is to not overdocument. Don’t start writing a comment for every single variable and function, especially if all you do is state the obvious. Examples…

This comment below is obvious and unhelpful. All the comment says is perfectly clear just by looking at the function.

/**
    This function does stuff with a prime number.  */
void do_stuff(int prime);

You should instead document how the function behaves in extreme situations. For example, what does it do if the parameters are wrong? If it returns a pointer, whose responsibility is it to delete the pointer? What other things should programmers keep in mind when using this function? etc.

/**
    This function does stuff with a prime number.
    \param prime A prime number. The function must receive only primes, it
    does not check the integer it receives to be prime.
                                                                               */
void do_stuff(int prime);

Also, I would advice you only document the interface in the header files: don’t talk about how the function does something, tell only what it does. If you want to explain the actual implementation, I’d put some relevant (normal) comments in the source file.