RE: [boost] Boost Doxygen documentation (was: 2000-10-22 Minutes )

From: Petr Kocmid (pkocmid_at_[hidden])
Date: 2000-10-31 19:07:14

> From: Beman Dawes [mailto:beman_at_[hidden]]
> *  What kinds of experiences are others having with Doxygen?
> What problems do they run into?

I am using doxygen for several projects. It's a great tool, with many
features far ahaed of any similar one. Unfortunately for boost, most
problems for me comes in documenting templates. Due to limited parsing
capabilities (lex stuff), some constructs are not understandable by doxygen.
I had problems with specialisations too. In such incidents, doxygen silently
produced completely different declarations in documentation than source code
was or placed the documentation under incorrect entry. However, there are
easy workarounds in such cases. And if anything else fails, generated docs
can always be changed manually ;-)

Using the tool itself is easy, it has a portable build system made in perl
and is accessible from cvs site.
Lamers could download precompiled binaries from web site.

I think the main reason of relative doxygen weakness  in templates is that
it is not commonly used with template libraries. I am sure boost usage of
the tool will be a great "boost" of doxygen itself!

BTW, some months ago, feeding doxygen with complete STLport was a killing
joke. At least for win2k...

Petr Kocmid
pkocmid_at_[hidden]

------- MSVC users only:
Here's example of part of my integration of doxygen invocation from Visual
Studio's Tools menu, may be helpfull for those who have "no time to learn
the new tool", as it was said. It's for 5 minutes:

Menu Tools/Customize/Tools, add the following:

Menu contents: Doxygen create new config file
Command: .....\doxygen.exe
Arguments: -g doxyfile
Initial Directory: $(FileDir)
Use Output window: on
Prompt for arguments: on

Menu contents: Doxygen rebuild doc
Command: .....\doxygen.exe
Arguments:
Initial Directory: $(FileDir)
Use Output window: on
Prompt for arguments: off

Menu contents: Doxygen update config file
Command: .....\doxygen.exe
Arguments: -u doxyfile
Initial Directory: $(FileDir)
Use Output window: on
Prompt for arguments: off

1. Open your project
2. Select some header file and run the "Doxygen create config file"
3. At the workspace windows add the "doxygen" folder to file view pane
4. Add the file "doxyfile" to the folder for easy editing
5. Edit the self-documented doxyfile at your will (tags INPUT, FILE_PATTERNS
and HTML section at least, maybe EXTRACT_ALL)
6. Select some file in the workspace window and run the "Doxygen rebuild
doc" command
7. Whenever new version of doxygen arrives with new options implemented, run
the "Doxygen update config" command

Now you have a complete documentation for your project. Provide source code
comments for the prose. Learn more tags to customize and beautify...