Boost logo

Geometry :

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.


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

Best regards,

Mateusz Loskot,
Charter Member of OSGeo,

Geometry list run by mateusz at