Re: [boost] [geometry] Documentation prototype for review

Subject: Re: [boost] [geometry] Documentation prototype for review
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2010-02-20 09:53:15

Paul A. Bristow wrote:
>> Mateusz Loskot wrote: I'm working on documentation of Boost 
>> Geometry based on Quickbook and I've prepared a prototype:
>> 
>> http://mateusz.loskot.net/tmp/ggl/qbk/
>> 
>> What I'm doing is manually porting the content from Doxygen-based 
>> (http://geometrylibrary.geodan.nl/) plus restructuring, 
>> reformatting and completing it with missing details.
>> 
>> I'd like to ask everyone who is interested in Boost Geometry 
>> library for comments, impressions and suggestions of improvements.
>> 
>> 
>> The Reference is one of the most important section I'd like to 
>> master, so please share your comments on the form and completeness
>>  of the concepts specification, for example:
> 
> This is looking nice - but so was the Doxygen based version.

The problem with Doxygen version is that it lacks of important details.
So, by the way of updating the documentation, we've decided to move to
Quickbook format. AFAIU, it is a preferred format for Boost docs.

> I believe (and found 'eating my own dogfood' -especially the SG plot
>  project) that the Doxygen produced Reference section is
> complementary to the more textual sections that you are writing.

Yes, that's right. I agree Quickbook work means more or less
manual rework of what Doxygen generates.

> Several libraries use both, see Boost.Units, Accumulator, (and of 
> course the NotAlibrary SVGPlot Soc 2007/vizisualization)

I have checked Acccumulator docs and I have to admit its reference is
nothing more to me than a headers/code browser.
It includes very little information.

The Units does it better and I've just learned that pages like this
http://www.boost.org/doc/libs/1_42_0/doc/html/boost/units/unit.html
is generated from Doxygen comments...hmmm

> and I think this is much the best way to go, especially as you have 
> already done the tedious task of adding Doxygen style comments to the
>  code, so that you (and readers) would lose much if you don't provide
>  it.

Yes, now I can see the point and that it's possible to combine both,
Quickbook and Doxygen. Sounds as the best option indeed.

> I found it was wise also to generate Doxygen only version first to 
> check you don't have any warnings - its quicker that way.

Doxygen lint-like functionality is helpful, indeed.

> Finally I would say that I found the Quickbook embedded code system 
> very, very useful. This ensures that the examples cannot get out of 
> sync with the code. and I found numbering sections 
> algorithms_append_hpp_1, algorithms_append_hpp_2 ... and also using 
> algorithms_append_hpp_output to show some or all of the output.
> 
> I put the output in a C comment like this [...] which can be 
> referenced by the QuickBook text.

Right, sounds like a very useful feature.

Paul, thank you for your suggestions. It opens new approach that seems
much better than hand-only crafted docs.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org