Re: [boost] Improving Documentation

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:
>
> http://www.boost.org/doc/libs/1_54_0/doc/html/boost_asio/reference.html
>
> and neatly gathers overloads and specialisations in clickable way
> leading to documentation of particular version of an entity:
>
> http://www.boost.org/doc/libs/1_54_0/doc/html/boost_asio/reference/read.html

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: 
<http://www.boost.org/doc/libs/1_54_0/doc/html/boost_container_header_reference.html>

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:
>
> http://www.boost.org/doc/libs/1_54_0/libs/spirit/doc/html/spirit/qi/reference/parse_api/iterator_api.html

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.