Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2013-10-10 18:58:07

Mathias Gaunard wrote:
> On 10/10/13 21:00, Andrew Hundt wrote:
>
>> http://www.boost.org/doc/libs/1_54_0/doc/html/boost_container_header_reference.html#header.boost.container.static_vector_hpp
>>
>> This second link is the typical header documentation throughout
>> boost. When I first started using boost it was months before I
>> realized that in these header synopsis I could click on the words of
>> the class to see the full documentation of that class,  in this case
>> "static_vector". Much of the time I just felt confused and lost. I
>> think this is indicative of a layout and user interface that needs
>> some improvement.
>
> Documentation like this is generated by preprocessing Doxygen XML
> output  to integrate it into Boostbook and have a good look for C++
> references.

> It has most of what you can expect from Doxygen + the Boostbook stuff
> which gives better cross-referencing than simple Doxygen.

Hmm - I looked at DOxygen and found it lacking for what I wanted.  I'm
also disappointed in the Doxygen generated documentation in boost which
to me mostly parrots the source code.  On the other hand, I think the
approach (literate programming) has promise but it seemed to me that
one would have to add a lot to Doxygen to generate what I would like
to see.  Maybe the "missing magic" is already in on our web site somewhere.
Basically I don't see where we can coordinate Boostbook with Doxygen.
Perhaps you could include the link which explains this.

Robert Ramey

> I personally don't understand how one cannot notice that the blue bits
> that become underlined when you hover them and change colors once
> visited are hyperlinks (especially since that's also true for any
> other hyperlink in Boost docs and most of the World Wide Web).
> What do you suggest would be better?

lol - I suppose you have a point.  But I made the same oversight.  What
happened was that I saw what looked like raw header files fromatted
to look good on the web page.  It looked like color coding.  It didn't
occur to me immediately that they were links which pointed to documentation.
I was expecting just the opposite - documentation linking to the the
header files rather than other way around.

Robert Ramey