Boost logo

Boost :

Subject: Re: [boost] Improving Documentation
From: Mathias Gaunard (mathias.gaunard_at_[hidden])
Date: 2013-10-11 08:42:12

On 11/10/13 12:12, Mateusz Loskot wrote:

> Yes, it does, but apparently it does not produce the quality
> Boost.Asio aimed for.
> The reference.xsl sheet produces clear index:
> and neatly gathers overloads and specialisations in clickable way
> leading to documentation of particular version of an entity:

I don't really know reference.xsl.

The default Doxygen postprocessing
($BOOST_ROOT/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl) gives a
list of header files with for each of them the symbols in them.
Something like the Boost.Container docs that were referenced earlier in
this thread:

So you say that reference.xsl (there are two of those, one in
tools/boostbook/xsl, one in libs/asio/doc, which one do you mean?)
generates some other layout with a symbol-centric approach rather than a
header-centric one?

The doxygen_xml2qbk tool in Geometry doesn't seem to be really like
Asio's documentation. It's not header-centric but otherwise it looks
pretty much like standard doxygen2boostbook docs.
Maybe people prefer this?

I personally quite like the header-centric approach, but that may be
because I'm just used to thinking in terms of header files first as the
structure of a library.

In any case, I'd be interested to know more about the differences
between doxygen2boostbook and xml2qbk to know which one I should use.

> The typical Boost way is to drop in everything into single Synopsis section,
> like here:

I wouldn't call any of the Spirit docs "typical Boost way".
This stuff is entirely handwritten as far as I know.

I personally find that the Spirit docs have some problems, because the
documentation is not always in sync with real code and because the
headers symbols were declared or defined in can be hard to find.

Boost list run by bdawes at, gregod at, cpdaniel at, john at