Geometry Boost List: [ggl] [quickbook] Algorithms quickbook sample

Subject: [ggl] [quickbook] Algorithms quickbook sample
From: Mateusz Loskot (mateusz)
Date: 2010-02-14 12:23:35

Barend Gehrels wrote:
>> I've added example of documentation of algorithms:
>>
>> http://mateusz.loskot.net/tmp/ggl/qbk/geometry/reference/algorithms/area.html
>>
>> Comments welcome.
>   
> Looking very well! When reviewing some questions and additions came up
> to me.

Perfect. I'm tentatively moving forward being not sure if all this looks
correct, so looking for questions and comments.

> Question: why are the tables numbered? Is that everywhere?

The table number seems to be generated automatically, see Fusion docs
for instance:

http://www.boost.org/doc/libs/1_42_0/libs/fusion/doc/html/fusion/iterator/functions/deref.html

> It might be good to add a "table" "return value" to denote the return
> value (in this case area_result). Area-result is normally expressed in
> the coordinate system of the input geometry, but in case of integer
> coordinates, it is converted to a double for obvious reasons.
> Area-result is also dependant on strategy. This information might be
> specified here or at a separate area-result page, but because it is
> dependant on these things, it might give more overview if it is done
> here (same for length-result, distance-result, etc).

Good point, as there are more than one return values possible,
so each should be described separately.
IMHO, the tables are good to maintain presentation clear, systematic
and comparable.

> I just also checked the perfect cplusplus reference, e.g.
> http://www.cplusplus.com/reference/algorithm/min/,

I've experienced errors on this website.
Personally, I prefer to rely on the C++ standard.

> and they have one
> section parameters (so no template parameters). I don't know if that is
> good, but I think it gives more overview to combine the table, so e.g.:

I decided to distinguish following other Boost docs as examples,
for instance Fusion:

http://www.boost.org/doc/libs/1_42_0/libs/fusion/doc/html/fusion/view/single_view.html

> *Table X. Parameters*
> 
> Parameter
> 
>     Type
>     Type requirement
> 
> Requirement
> 
> Description
> 
> |geometry|
> 
>     Geometry
>     Models of one of geometry concepts <../geometries/concepts.html>    
> 
> Shall form a valid geometry
> 
> Polygon should be closed and according to specified orientation
> (clockwise or counter-clockwise)
> 
> |strategy|
> 
>     Strategy     Models of AreaStrategy    
> /TODO/
> 
> Specifies algorithm of area calculation, especially useful for spherical
> areas where number of approaches are possible

So, basically, do you mean to merge Template Parameters
with Parameters tables to one?

> We once decided that pointy and linear geometries return an area of 0
> here. The alternative is "not compile" which is inconvenient for
> environments where things are handled genericly, so they don't know
> which geometry-type they handle, and "exception" which is often also
> inconvenient.
> http://thread.gmane.org/gmane.comp.lib.boost.devel/186625

OK, once decision is made, we can document it.

> Question: the synopsis is missing the typename keyword, is that on
> purpose?

I copied the prototype as it is presented by the Doxygen-based
reference:

http://geometrylibrary.geodan.nl/group__area.html

The typename should be included, so I've fixed it in *.qbk
file in SVN.

> How do other boost libraries handle this?

As far as I have learned and know, synopsis is supposed to present
complete prototype of a type or function.

> You suggested that the performance section will be replaced with
> complexity so I think that still is to be done. 

Yes, IMHO complexity is a better name.
Performance may suggest that this is about benchmarking, but it is not
supposed to be. It is about explaining computational complexity
guarantees and requirements, not about benchmarking.
Actually, I'm unsure about including any timing in this section, but
just raw complexity detail.

> The complexity of area calculation is linear.

Updated.

> Some more information: the area is positive for geometries ordered
> according to their orientation. The area is negative for interior rings
> (again, ordered according to their orientation). Invalid polygons (e.g.
> ones having an interior ring larger than the exterior ring) might result
> in a negative area as well.

Where do you think these details should be presented?
For example, in description field of the proposed table Return Type?

Thanks for comment!

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