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

[Dimitri v. H. <di...@st...>]

On Mon, Mar 11, 2002 at 01:44:15PM -0600, Scot Wilcoxon wrote:
> 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.  

Well, doxygen's documentation is generated by doxygen, so how is that 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.

I guess you mean doxygen is meant for code related reference manuals and not
for user manuals. Well that's right. 

> 
> 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.

Hmm, I get the feeling someone is a little frustrated... Why not help to
improve doxygen instead of complaining about it not working the way you want?

Regards,
   Dimitri