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

From: Eric Weitzman (eweitzman_at_[hidden])
Date: 2000-10-31 14:03:48

Hi, Beman.

I've just done a cursory evaluation of the free document generation
tools out there. I looked at object outline, web++, ccdoc, doc++,
cocoon, cxx2html, rethreec++, robodoc, scandoc, and doxygen.
Doxygen seems to be the most comprehensive. A caveat here is that I
haven't put it through it's paces on a full project yet. I'm going
to give it a trial run this week.

In response to some of your specific queries:

*  Is the generated documentation good enough?  Examples I have seen are 
   only partially convincing.  They always seem to skimp on prose 
   descriptions.

That's up to the person authoring the comments in the code. I assume
you're not talking about the actual layout of the html documentation.
If you read the javasoft guidelines, they don't advocate full prose in
all cases, and are happy reading (like most programmers are happy
writing) pithy phrases instead of full prose in certain cases.

*  Does Doxygen reduce the readability of source code?

Virtually all of the programs I looked at insisted that you place all
documentation in the header files. The argument for this is that the
interface exposed to consumers/other programmers is published in
headers, so that's where the documentation-as-contract belongs. I
personally find reading a header in which the comment-to-code ratio is
any more than about 1:5 very irritating. Doxygen, on the other hand,
will retrieve comments from the implementations, and has rules that
determine what gets used if a function or member is documented in both
places. So, you can put the pithy contract-based stuff in the headers
and implementation related comments in the code as they're discovered
during development. And since your consumers can read the collected
documentation in their browser, it doesn't matter to them where the
documentation came from.

Another nice feature is that Doxygen will (optionally!) generate pages
that contain color-coded headers and implementation, hyperlinked back
to the documentation pages, without the doxygen comments! Back to the
spirit of web and tangle/weave!

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

Doxygen will produce documentation even without commented code. This
doesn't add anything to your understanding of particular functions,
but it still provides inheritance hierarchies, what it calls
"interaction diagrams", cross referencing, interdependencies, and so
on. It basically makes the implied structure that's distributed through
many source files more obvious, centralized, and readily navigated.

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

Only if your standards insist on documented code that uses Doxygen
(javadoc-style) comments.

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

Too early to comment.

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

Doxygen has a few tags that cover todo items and test case tracking,
so these issues can be elevated from dark places deep in the code to
higher visibility. It can also retrieve narrative text from files
outside of the code per se, so the install and build instructions can
be integrated with the generated documentation.

I'm really happy to have found a tool (doxygen+graphviz) that builds
class diagrams for me without having to resort to Visio or Rose.

- Eric