Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2013-10-15 12:31:37

Mathias Gaunard wrote:
> On 14/10/13 19:39, Paul A. Bristow wrote:

> Doxygen is for documenting entities of the C++ language within C++
> source code. Concepts are not entities in that language and do not appear 
> in the
> source code, and thus cannot be documented by Doxygen.

I spent some time looking into Doxygen for just this purpose.  I concluded
that it might be possible to generate Concept Documentation by marking
up the concept checking classes.  I thought this was cool idea an that it
would also encourage authors to actually make concept checking classes.
Having concept checking classes almost makes it imperitive to insert
them into your library code - which then reveals design problems
in one's library at an early stage.  I see this as the holy grail* of C++
library development.  Doxygen includes a lot of ability be
customized so this is very interesting.  But when I looked deeper
I concluded that trying to do this customization would lead to yet
another complex, fragile, unfinished and hard to use tool.  I wanted
to move to simpler tools.   The future looks bright and we're moving
in the right direction - but we're not there yet.

> I'm talking about defining the concept itself in Boostbook, which is
> an XML format.
> See for example the various xml files at
> $BOOST_ROOT/libs/proto/doc/reference/concepts/
> which generate
> <http://www.boost.org/doc/libs/release/doc/html/proto/reference.html#proto.concepts>

Note taht Boostbook has a bunch of special tags for C++ entities.  It
seems to me that no documenation actually uses them.  I'm sure that
this is due to unwieldyness of editing boostbook xml and quick book
doesn't got that deep.

> Interestingly, as far as I can tell, only Boost.ConceptCheck and
> Boost.Proto use the real Boostbook format for concepts (my own
> libraries  not accepted into Boost also do)

Hmmm - since I think BoostConceptCheck and BoostBook have
the hand of Doug Gregor in them.

> Writing those XML files by hand is indeed not great,

it's much worse than "not that great" it's unfit for human activity
and it's hell to maintain.

I use XMLMind along with a custom made DTD for boost book.

> extend Quickbook or use another tool to generate them instead.

Quickbook is a great tool.  It has a lot of stuff "baked in" which makes it
easy to use.  But that's its weakness as well.  When I wanted to add
something to it - like generating concept documentation, It looked like
I would have to add to the source and recompile - which leads me down
a path without an end.  This is the path of many of our tools.

That's why I looked elsewhere.

Robert Ramey