From: Alan Griffiths (boost_at_[hidden])
Date: 2000-10-31 14:57:25
In message <18.104.22.168.2.20001031111119.00b29a60_at_[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
>* 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]) http://www.octopull.demon.co.uk/ ACCU Chairman (chair_at_[hidden]) http://www.accu.org/
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk