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

From: Jeff Garland (jeff_at_[hidden])
Date: 2000-10-31 23:03:28

Beman -

First off, I agree with most of what Eric and Alan 
had to say, but here are some additional thoughts...

Beman wrote:
> *  Is the generated documentation good enough?  Examples I have seen are 
> only partially convincing.  They always seem to skimp on prose 
> descriptions.
That's true.  I have seen plenty of bad documentation from
generators(much of it generated from equally ugly code).
Since I made NO modifications and none of the code is 
instrumented I expect the actual comments to be minimal.
In fact, while I think it would be cool to have the code
commented I learned allot about boost without the comments.

I find it extremely valuable to be able to see the 
relationships.  I don't know about you, but I am unable
to dig out the inheritance graph from reading the source (ok,
I can do it, but it is a pain and I never get to browse the 
whole library like I can with the generated docs).  Also,
I find it handy to be able to follow the links in the
HTML version of the code.  If you look at the link
below, you will see that the header files are hyper linked as
well as the other referenced classes (see line 200).
http://www.crystalclearsoftware.com/users/jeff/boost/random.hpp-source.html

Also, I was responding to Joerg's point about include dependencies.
Again, this is a valuable reference when trying to understand the
structure of the library implementation.  

> *  Does Doxygen reduce the readability of source code?

No.  Eric and Alan covered this pretty well, but suffice it
to say that nice documentation can be created with minimal 
intrusion on the source.  In fact it is up to the developer
how much to put in the source since it can all be taken out
of the source. However, usually it is nice to maintain the
comments near the code so that the comments get updated
as the source changes.

For example, the following is the syntax for a "one-liner"
description which works for functions, classes, methods,
template classes, and attributes.  
//!class foo provides blah, blah, blah
/*!This syntax provides an extended description (for class foo
  in this case. As Eric pointed out this stuff can go in headers, 
  cpp files, or stand alone files.  The bottom line is the 
  developer still has total control over the readability.
*/
class foo {};

> *  Is Doxygen practical if only some boost library developers use it?

Yes I believe so.  As my demonstration points out, some level
of documentation is available without any code changes.  I believe
that each library maintainer can choose how much they want to provide.
However, I agree with Alan that the overall value declines if there
is not at least some minimal consistent level.  I would say the
minimal level is that every class have at least a one line
description.

> *  Does Doxygen create an impediment for developers wanting to submit 
> libraries to boost?  Developers should not have to learn a new tool.

On the contrary, I believe it will be a productivity aid.  Library
developers that invest just a bit of time will be able to produce
high quality library docs with less effort.  For example, most
parts of the library already need to build synopsis information
about each class.  

On the other hand, I could see someone just following the coding 
standard, never using the tool, and getting the docs generated 
auto-magically as part of a build or release process.  

As for running the tool, let's say someone sat down and figured
out a nice set of options and put them in the config file (called
Doxyfile).  Then running the tool comes down to typing: doxygen
(or some windows thing in VCC).  It doesn't get much easier.
Also, for those that what to tweak the parameters, the 
documentation is outstanding.

> *  What kinds of experiences are others having with Doxygen?  
> What problems 
> do they run into?

So far, it has worked really well for me.

> *  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?

Overall, I think the boost documentation is good.  However,
the library is getting big fast and it is already a bit overwhelming. 
In addition, the documentation is not up to the level of the 
JAVA libraries or libraries such as Rogue Wave.  

Right now, I would agree that install, build, and test are a higher
priority.  However, I would love to see library developers adopt
Doxygen because I believe that authors will find it can improve 
their documentation and make the documentation development easier. 

Jeff