[Doxygen-users] \file - global variables and functions not documented - reasoning

[Maciej W <tri...@gm...>]

Greetings,

I have a question from the theoretical point of view.
Lets suppose we have a *.h header file in which there are:
- class declarations
- namespace declarations
- global function declarations / global variable declarations
Lets additionally suppose all of those (class, namespace, global stuff
declarations) _lack_ explicit documentation blocks.
Then, if doxygen is run against that *.h file with the following settings:
- EXTRACT_ALL = NO
- EXTRACT_LOCAL_CLASSES = NO (for clarity)
then 'declaration' parts of classes and namespaces _are_ in the resulting
documentation but declaration parts of global functions / global variables
_aren't_.

If /** \file */ is added to the *.h file, then doxygen does generate
'declaration' part of the documentation for global functions / global
variables.

So the question is this: why is there a separation between
classes/namespaces and {global variables and global functions}?
I've initially made a rule that, when there is no explicit documentation
for a given entity, then even if EXTRACT_ALL is disabled, Doxygen _still_
generates [at least] the 'declaration' part of _any_ entities found in
header files. But this rule for some reason doesn't hold for global
functions / variables and I'm wondering what's the reasoning behind that.
What I'd expect from doxygen if \file is not in the *.h file would be to
_do_ generate 'declarations' part of the documentation for global variables
/ global functions (along with classes or namespaces).
Or, do not generate class/namespace 'declarations' part of the
documentation if \file is missing in the file that (the file) contains the
declaration of a class/namespace.
Or something like \filenamespace \fileclass \fileglobal to discern between
all of those cases:
- \filenamespace - if present, extract namespaces out of file even if those
namespaces not documented
- \fileclass - if present, extract classes out of file even if those
classes not documented
- \fileglobal - if present, extract global vars/fns out of file even if
those classes not documented

So again, what's the design decision behind, when no explicit documentation
for a given entity exist, extract 'declaration' part of namespaces/classes
but leave out {global variables / functions}?

Lets leave out the discussion of source files (vs header files) for now for
this.

Cheers.