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

From: Beman Dawes (beman_at_[hidden])
Date: 2000-10-31 11:34:24

Jeff,

Thanks for taking the trouble to run the boost libraries through Doxygen, 
and posting the results for us to look at.

My worries about Doxygen include:

*  Is the generated documentation good enough?  Examples I have seen are 
only partially convincing.  They always seem to skimp on prose 
descriptions.
*  Does Doxygen reduce the readability of source code?
*  Is Doxygen practical if only some boost library developers use it?
*  Does Doxygen create an impediment for developers wanting to submit 
libraries to boost?  Developers should not have to learn a new tool.
*  What kinds of experiences are others having with Doxygen?  What problems 
do they run into?
*  Negative comments about boost seem to center on library install, build, 
and test issues.  I haven't heard a lot of complaints about the detailed 
documentation for libraries. Is there actually a need to change the way we 
do library documentation?

Comments?

--Beman

Jeff Garland wrote:

 >Joerg Schaible wrote:
 >> reading the minutes, I detected the 3.2.2 dependency problem. A
 >> proper tool
 >> to use may be DoxyGen (www.doxygen.org), that I mensioned some time ago 

 >as
 >> we've discussed for a proper documenttaion form. Although its main
 >purpose
 >
 >I also believe doxygen has alot to offer the boost community and have
 >suggested
 >it be adopted to assist in library documentation.  To give everyone an 
idea
 >of the potential I have generated a set of html documentation for the
 >current
 >boost release.  I have found this useful when trying to find things and 
see
 >how they fit together.
 >
 >Here are some highlights:
 >
 >Example of Dependency Graph for Config.hpp
 >http://www.crystalclearsoftware.com/users/jeff/boost/config.hpp.html
 >
 >Index of all boost files (headers only)
 >http://www.crystalclearsoftware.com/users/jeff/boost/files.html
 >
 >Textual Class Hierarchy
 >http://www.crystalclearsoftware.com/users/jeff/boost/hierarchy.html
 >
 >Graphical Class Hierarchy (Warning this is a graphics intense page!!!)
 >http://www.crystalclearsoftware.com/users/jeff/boost/inherits.html
 >
 >
 >Of course, this only shows part of the potential, because the source
 >has not been instrumented with appropriate comments to provide namespace,
 >class, and member descriptions.  With some minor source changes the
 >documentation
 >would be even more useful.