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

From: David Abrahams (abrahams_at_[hidden])
Date: 2000-10-31 14:38:41

My impressions below:

----- Original Message -----
From: "Beman Dawes" <beman_at_[hidden]>
> 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.

Unfortunately, Doxygen requires a special syntax (e.g. "///") in the
comments for them to be picked up by the tool (I would prefer a tool which
errs in the other direction by default). Since boost doesn't have any of
these yet, the example you're seeing is of course a bit skimpy.

> *  Does Doxygen reduce the readability of source code?

Not much. Syntax like "///" doesn't hurt much. There are some fancy
directives which could affect readability if used a lot, but I think the
need for these is rare.

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

Probably. If some libs don't have any special comments, the result will be
no worse than the samples you've seen. I wouldn't want to replace the
documentation we have now with Doxygen-generated docs, but Doxygen could be
really useful to help document internals.

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

No opinion.

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

constructs like this:

template <class B>
class Derived : public B {};

end up showing Derived inheriting from a class called 'B' in the inheritance
graph. IOW, it doesn't distinguish class templates/type parameters from
actual classes. I'm not sure this is a bad thing, though. All the same, I'd
wager it trips over specializations.

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

Maybe. For complicated libs like BGL, regex, or py_cpp, an outside developer
who wants to fix a bug or add a feature may need help grasping the overall
structure beyond what's provided bythe source code .

-Dave