# Geometry :

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

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

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.