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