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
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);
-- Mateusz Loskot, http://mateusz.loskot.net Charter Member of OSGeo, http://osgeo.org
Geometry list run by mateusz at loskot.net