Boost logo

Boost :

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


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