Re: [Doxygen-users] Documentation generation

[Dave D. <do...@do...>]

On Wed, Jun 28, 2006 at 06:42:08PM +0100, Manuel Esteves wrote:
> I have a project written in C language that has the header files(.h)
> and the source files (.c).
> 
> Do i have any advantage in inserting the tags for documentation
> generation on boths files?

I try to follow some basic principles:

  - Document something in the minimum number of places.
  - Keep the documentation close to the code.

My goal is to make it as easy as possible to keep the documentation in
sync with the code, and as easy as possible to spot places where the
documentation needs work.

I normally document things alongside their definitions.  For example
most functions are documented in their .c file, but an inline function
might be documented in a .h file if that's where it's defined.

An advantage to this is that header files are kept small, which means
that they serve as a nice quick reference for an API when all you need
is a reminder of the function names.

A special case is when a single header has multiple .c implementations
available.  For example I might have functions that use
machine-specific details and are implemented for multiple
architectures; or I might implement a complete API multiple times
using different storage methods internally.  In these cases I document
the declarations in the header, so that if the API changes I only have
to update the documentation in one place.

                                                  -Dave Dodge