Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2013-10-11 09:43:31

On 11 October 2013 13:42, Mathias Gaunard <mathias.gaunard_at_[hidden]> wrote:
> 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.

This is the one I'm referring to:
<https://svn.boost.org/svn/boost/trunk/libs/asio/doc/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>

IMHO, that is a useless kind of documentation.
We've got IDEs and editors with decent code browsing capabilities for that.

> 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?)

I mean the second one.

> generates some other layout with a symbol-centric approach rather than a
> header-centric one?

Yes.

The basic idea is this:
If I click a function name, I get details of that function.
If I a function has more overaloads, I get extra intermediate page -
listing of overloads.
If I click a parameter, I get corresponding concept with its requirements.

For example,
1) one of overloads
http://www.boost.org/doc/libs/1_42_0/doc/html/boost_asio/reference/async_read/overload3.html
2) click on template parameter AsyncReadStream
http://www.boost.org/doc/libs/1_42_0/doc/html/boost_asio/reference/AsyncReadStream.html

Such documentation is based on the natural process of reasoning about C++ Code.

> The doxygen_xml2qbk tool in Geometry doesn't seem to be really like Asio's documentation.

As I mentioned, we've reached Asio-like prototype some time ago [1] ,
but due to XSLT
complexity we've switched to simple generator, though it's not as
capable as Asio's, yet.

[1] (links broken, no longer online)
http://lists.boost.org/Archives/boost/2010/02/161827.php

> It's not header-centric but otherwise it looks pretty much
> like standard doxygen2boostbook docs.
> Maybe people prefer this?

Might be users prefer it, At least, that's what Geometry team prefers :-)

> 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.

I do as well, but I use code browsing tools for that.

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

Barend described how it works for Geometry:

http://barendgehrels.blogspot.co.uk/2010/12/doxygen-and-quickbook.html

>> 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 find handwritten docs superior. The Doxygen comments make the code
harder to browse, especially if programmers aspire to stick long essays
with numerous code examples into them.

IMHO, Doxygen comments should be very minimal and the bloat of documentation
in separate Quickbook (or Markdown) files cross-referencing to symbols from
code and Doxygen (separate plain text files with dosc make it
easy to read without generating HTML/PDF, etc.)

But, I guess we're getting into personal preferences
There used to be a very long debate on boost-docs [1] about
pros/cons of Doxygen
and the outcome was within Boost, there are people who hate it
and people who love it, hence best is to allow freedom of choice.

[1] "Sphinx integration" thread :)
http://lists.boost.org/boost-docs/2011/09/
http://lists.boost.org/boost-docs/2011/10

Best regards,
-- 
Mateusz  Loskot, http://mateusz.loskot.net