Geometry Boost List: [ggl] [doc] New draft of Reference based on Doxygen-to-Boostbook

Subject: [ggl] [doc] New draft of Reference based on Doxygen-to-Boostbook
From: Mateusz Loskot (mateusz)
Date: 2010-09-09 18:53:16

On 04/09/10 11:27, Barend Gehrels wrote:
>>
>>> - the reference pages can be quite documented, (possibly) having code
>>>  snippets, behavior, complexity, images,
>>
>> As I've suggested, I'd rename Snippets to Examples.
> 
> No problem, will be done.

Barend,

I have some additional comments to the examples.

In my opinion, the examples should state short and well-formed
C++ programs, but not just snippets showing basically how to substitute
argument names with values - it should be clear from reading
documentation anyway.

Such "one-liners" are in my opinion not very encouraging for user
trying the library for the first time, neither helpful for those who
are not C++ zealots.

It means, I'd like to see those examples as short programs that
users can copy & paste & compile & try without touching them.

Second, the comments should be inlined in examples source code,
but not just referred by numbers. It is easier and more
convenient to track code & explanation if presented in this form:

// Set a coordinate. Note: prefer using bg::set<0>(point1,  1.0);
point1.set<0>(1.0);

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