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

Subject: [ggl] [quickbook] Algorithms quickbook sample
From: Barend Gehrels (Barend.Gehrels)
Date: 2010-02-14 05:24:20

Hi Mateusz,

> 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.

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

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

I just also checked the perfect cplusplus reference, e.g. 
http://www.cplusplus.com/reference/algorithm/min/, 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.:

*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

   

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

Question: the synopsis is missing the typename keyword, is that on 
purpose? How do other boost libraries handle this?

template<typename Geometry>
*typename *area_result<Geometry>::type area(Geometry const& geometry)

You suggested that the performance section will be replaced with 
complexity so I think that still is to be done. The complexity of area 
calculation is linear.

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.

Regards, Barend

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/ggl/attachments/20100214/ae37073c/attachment.html