As I write programs, mainly in C++, I document them using the Doxygen tool. This is a very powerful parser that is capable of finding functions, variables, macros, and many other things in the source code and attach the corresponding documentation to those functions, variables, macros, etc.

This is extremly practical when creating large projects or libraries that you want to share with others.

One problem though, by default it seems like global functions (and thus C functions) and variables do not make it to the documentation, when C++ classes work fine.

Here are two potential issues in that regard:

EXTRACT_ALL

The EXTRACT_ALL flag is set to NO. This is the default and it is expected to remain set to NO. By setting the flag to YES you already get many more definitions in your output but still not everything.

However, setting this to YES has some side effects that are often unwanted. Therefore I suggest you instead use the following trick.

@file

Files are considered private by default. This means files that do not have the @file declaration (or \file) are ignored and not included in your Doxygen output, except for members of C++ classes.

Yes! It is that simple. Edit your C/C++ files, go anywhere you want, and add @file in a comment, probably with a @brief description too:

@file
@brief This file is marvelous.

Note that the @file accepts the name of the file as a parameter, but since it defaults to the expected name of the file you're documenting, it is not required.

Although it is possible to define all your files in one single documentation file. Obviously, in that case the filename is required.

One other reason is when you generate a file from another. To place the documentation in the generated file, but reference the source, using the source filename is useful:

@file source.file
@brief blah blah blah...

This way you'll finally get everything as Doxygen will not skip the documentation you wrote for your C files and any C++ global funtion, variable, etc. It is also not a bad idea to indicate what a file is about and instead of putting that info in a standalone comment at the top or bottom, using the @file makes it readily available to your docs as well!

No name namespace

When you create a set of private declarations, variables, functions, classes, etc. in an unnamed namespace, you actually get a form of special namespace which Doxygen still has a hard time with.

The C++ compiler often show you errors with something like this:

n1::<no-name-namespace>::n2::varname

where the <no-name-namespace> is your unnamed namespace in that one file.

The Doxygen parser is not currently doing that. Their issue (I think) is that they can't add a namespace because if the search mechanism they are using to find the various variables, classes, etc. found in the unnamed namespace.

In any event, to fix this issue, I've used a Doxygen Trick:

1. Make sure you have a DOXYGEN predefined and expand the no_name macro

PREDEFINED             = DOXYGEN=1
EXPAND_AS_DEFINED      = no_name

2. In my projects, I create a doxygen.h header file with:

#ifdef DOXYGEN
#define no_name doxygen
#else
#define no_name
#endif

3. In each file with an unnamed namespace

namespace no_name
{
... private definitions ...
}

What this means is: if we are running Doxygen, use the name "doxygen" for all those unnamed namespaces, otherwise use nothing (i.e. then it's really an unamed namespace).

Of course, this is wrong as far as C++ is concerned since that would mean that the declarations in those paragraphs would be visible in the entire software. That's exactly what helps Doxygen. Now, of course, if you have definition using the same names in separate files, Doxygen is likely to make mistakes and choose the first definition it found instead of the one in the same file. However, 99% of the time, this is a lot better than not having proper support for unnamed namespaces in your documentation.