Subject: [ggl] [quickbook] Algorithms quickbook sample
From: Barend Gehrels (Barend.Gehrels)
Date: 2010-02-14 05:24:20
> I've added example of documentation of algorithms:
> Comments welcome.
Looking very well! When reviewing some questions and additions came up
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*
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 Models of AreaStrategy
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
Question: the synopsis is missing the typename keyword, is that on
purpose? How do other boost libraries handle this?
*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.
-------------- next part --------------
An HTML attachment was scrubbed...
Geometry list run by mateusz at loskot.net