Re: [Doxygen-users] Understanding how Doxygen Documentation is generated

[Scot W. <sc...@wi...>]

Quoting: Bob Stafford <do...@bo...>
> I'm trying to use doxygen to generate general documentation, in the same
> way that is appears it is used to generate the doxygen documentation
> itself, but I'm having some problems understanding how this documentation
> is generated.

I'm having similar problems and have concluded that the author of Doxygen has 
limited its scope to only libraries and variable declarations.  A number of 
reported awkwardness in usage are due to people pushing through Doxygen's fuzzy 
boundary between a library of functions and applications which reuse common 
functions.

I believe the Doxygen-generated documentation on its web site is produced by a 
simple technique:  he's cheating.  

Doxygen can not create documentation for a program, only for a library.  So the 
web site's Doxygen-created documentation is created from files with Doxygen 
commands, but that documenation is not within the Doxygen source code.

That is why the Doxygen source includes a "doc" directory full of documentation 
files, and Doxyfile is within the doc directory.

That is why doxygen.cpp does not contain an @file Doxygen statement.

That is why doxygen.cpp does not have its own functions documented with Doxygen.

That is why Doxygen does not have a command to create a link at the top of 
mainpage for Application programs.  No files are known as Programs.  Go to 
http://www.graphviz.org/ and look at the Doxygen documentation: one of the 
tools is called "dot" but try to learn anything about it..yes, its main() 
happens to be in dot.c -- then try to find one of the other utilities without 
knowing what they are called.

That is why the function usage() prints the command line options, but to 
properly document a program you have to have the command line options three 
times: in the code which emits the usage message, in the Doxygen comments 
(after @file and @brief), and if you want them on the Doxygen-generated main 
page again in a section labeled with @mainpage.

That is why the man page is labeled with language suffix such as ".c" in the 
name: myutility.c.8 rather than myutility.8 -- and all the man pages get the 
same suffix so if you make the main program be myutility.c.1 then all the 
function documentation also gets *.1.

That is why Doxygen has no ability to document program flow nor extracting 
program flow from the code.  You can't make it generate a text file with your 
comments of which functions are called in what sequence, what an "if" statement 
is doing, much less emit a GraphViz flowchart.