Geometry Boost List: [ggl] Writing Documentation for Boost

Subject: [ggl] Writing Documentation for Boost
From: Mateusz Loskot (mateusz)
Date: 2010-02-23 18:33:56

Folks,

I didn't know about this document earlier, but it looks as a valuable
guide for further reference while reviewing various aspects of Boost
Geometry documentation:

http://www.boost.org/doc/libs/release/more/writingdoc/structure.html

Currently, I'm working on integration of existing Doxygen-based
documentation with Quickbook. It is very promising and should allow to
exploit the valuable docs we already have injected in the source code.

However, there is a need for update and a bit of restructuring.
I've already planned to follow some of best examples of docs among boost
libraries regarding what elements to document, what we have missing,
etc. and as I see the guide above does refer to such topics as well:
It is, I will also focus on updating/documenting function semantics,
as appropriate.
http://www.boost.org/doc/libs/release/more/writingdoc/structure.html#detailed-specs

The interesting note is about complexity:

http://www.boost.org/doc/libs/release/more/writingdoc/structure.html#complexity

"(...) is often not desirable because it over-constrains implementors
and is hard to specify correctly. "

Confronting this with the fact how much attention is focused on
complexity during reviews one may get confused, indeed.

Anyway, I'm in diving to another iteration of docs, giving up with
previous idea "write everything to "Quickbook by hand" replacing it
with "generate Doxygen and add manually what's missing".

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org