Subject: Re: [boost] Improving Documentation
From: Mathias Gaunard (mathias.gaunard_at_[hidden])
Date: 2013-10-11 08:46:47
On 11/10/13 00:47, Andrew Hundt wrote:
> I completely agree that boost docs should generally be a "how to use"
> guide. The additional steps I also think would be reasonable are for the
> "how to use" detail to be easier to browse around and links to all the
> existing examples and tests.
There are two parts to a documentation:
- a reference documentation, which says non-ambiguously what a
function does, what its preconditions are, which file it is in, etc.
It is easy to agree upon the fact that this documentation should be
written with Doxygen to ensure that it's always in sync with real code.
- a tutorial, that explains the domain and how to approach using the
library to solve some problems. This is better written separate from the
library using Quickbook (or ReST or any other similar language).
Standardizing all Boost documentation for the reference part would be
Each library seems to do its own thing for this, with varying levels of
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk