RE: [Doxygen-users] Understanding how Doxygen Documentation is ge nerated

[Voshell, J. <vo...@me...>]

Well... it's free, and you have the source, so if you don't like it, fix it.
(then post it so we all can benefit).


-----Original Message-----
From: Scot Wilcoxon [mailto:sc...@wi...]
Sent: Monday, March 11, 2002 2:44 PM
To: dox...@li...
Subject: Re: [Doxygen-users] Understanding how Doxygen Documentation is
generated


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.

_______________________________________________
Doxygen-users mailing list
Dox...@li...
https://lists.sourceforge.net/lists/listinfo/doxygen-users