Boost logo

Boost :

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

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

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:

>* 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.)


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])
ACCU Chairman   (chair_at_[hidden])   

Boost list run by bdawes at, gregod at, cpdaniel at, john at