I’ve just started writing Boost.Geometry (aka GGL) documentation in Quickbook. It is a lightweight format and parser being developed by Boost used to prepare technical documentation for software, mainly for for Boost C++ Libraries. Quickbook files (.qbk) are used as input for BoostDoc which in turn is an extension of DocBook.
Quickbook is a textual format, it feels quite similar to AsciiDoc or some sort of Wiki dialect but dedicated for documenting C++ programming. It is extremely easy to grasp while drinking a single short coffee.
Anyway, it seems it is going to be a quite a book after all elements of Boost.Geometry are documented. One of the challenge I’ve found is to collect all bits necessary to document C++ concepts defined by Boost.Geometry. Unfortunately, Doxygen is not an ideal tool for this purpose, so current version of the documentation lacks of some sections of concepts description. So, I have to dig the source code to find out formal definitions and details of valid expressions and semantics.
Another challenge related to concepts is to find best way to structure their documentation. I started to browse documentation of existing Boost libraries looking for examples and what I found is that there is no best example. Various libraries document concepts in very different way.
A concept is a set of requirements consisting of valid expressions, associated types, invariants, and complexity guarantees
– David Abrahams, Generic Programming Techniques
For example, neatly Boost.Fusion documents concepts with Quickbook, though some elements seem to be omitted. Boost.Graph doesn’t document with Quickbook, looks good, but some details are missing to me, for instance, titles in headers of tables saying what is what is return type and pre-/post-condition for valid expressions, etc. Documentation of Boost.IOStreams concepts sound well. On the other hand, Boost.GIL is an example of why Doxygen should not be used to document concepts of a C++ library.
It looks to me the old good Standard Template Library Programmer’s Guide at SGI is still a best and most complete example of how C++ concepts should be documented.
Given these experiences, I started to think of a way to improve the way concepts are documented within Boost. I believe it would be a good idea to have predefined block for concept in Quickbook. Something along these lines:
[concepttype [Point Concept]
[this is a concept for 0-dimensional geometry]
[notation
[term 1] [description 1]
]
[refinement [concept 1] [concept 2]]
[associated
[type 1] [description 1]
]
[expressions
[name 1 [expr 1]
[type requirement 1] [return type 1]
]
[semantics
[name 1 [expr 1]
[precondition 1] [semantic 1] [postcondition 1]
]
[complexity [...]]
[invariants
[invariant 1] [description 1]
]
[models [model 1] [model 2]]
[notes
[ note 1] [ note 1]
]
[seealso ...]
]
I posted my proposal to boost-docs list explaining the motivation in details. It’s an interesting experience of a C++ documentation craftsman, anyway. (BTW, Daniel James just announced Quickbook port to Spirit 2.)
