
Geometry : 
Subject: [ggl] [quickbook] Algorithms quickbook sample
From: Barend Gehrels (Barend.Gehrels)
Date: 20100214 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). Arearesult 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.
Arearesult is also dependant on strategy. This information might be
specified here or at a separate arearesult page, but because it is
dependant on these things, it might give more overview if it is done
here (same for lengthresult, distanceresult, 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 counterclockwise)
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 geometrytype 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
Geometry list run by mateusz at loskot.net