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

From: Alan Griffiths (boost_at_[hidden])
Date: 2000-10-31 14:57:25

In message <4.3.2.7.2.20001031111119.00b29a60_at_[hidden]>, Beman
Dawes <beman_at_[hidden]> writes
>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.

The documentation can be good enough - there are adequate hooks for
linking to external tutorials and the like.

There is a "real life" use of Doxygen at:

    http://www.octopull.demon.co.uk/arglib/

>*  Does Doxygen reduce the readability of source code?

This is subjective - there is no need for more than a few characters
that ought to be there anyway (IMO).  I have colleagues that feel any
comments in class bodies reduce readability (no that isn't just in code
they're writing).

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

Yes, but it looses value.

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

I doubt it - and only a minimum comment markup is required to get a
nicely formatted return.

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

Its grasp of C++ syntax isn't complete - which can lead to oddities in
the documentation, and its matching of names is simplistic - and
sometimes leads to strange results.

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

I think that having a build process is more important.  (Even if it is
simply an example GNU Makefile.)

>Comments?

As a general point a standard (de-facto or otherwise) documentation tool
for C++ would be useful for the community.  If Boost contributors want
to contribute to establishing the tool or the standard I wouldn't object
but it isn't the purpose for which Boost was conceived.
-- 
Alan Griffiths  (alan_at_[hidden])  http://www.octopull.demon.co.uk/
ACCU Chairman   (chair_at_[hidden])             http://www.accu.org/