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

Subject: [ggl] [quickbook] Algorithms quickbook sample
From: Mateusz Loskot (mateusz)
Date: 2010-02-14 18:20:45

Barend Gehrels wrote:
>>> 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?
> 
> Yes, that was actually mu suggestion (so tables are OK, but nearly all
> parameters are template parameters, having parameter type together with
> parameter name seems convenient to me. What do other Boost libraries use
> here?

OK, I see your point.
As I've mentioned, other libraries do it very differently.
It is very hard to figure out any unified convention.
So, I decided to look at those documented with Quickbook only,
meaning fairly recently documented like Fusion,Range, Accumulator
or Property Tree.

Some libraries do not even document template parameters.

>>> 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.
>   
> Yes, it is made.

So, you mean to add a note about the these non-surface types?

>> Actually, I'm unsure about including any timing in this section, but
>> just raw complexity detail.
>>   
> So yes, they may be deleted here.

OK, I'll do it.

>>> 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?
>
> Eehm, actually these are details. I later saw that you mention "valid"
> input (or I did before). So remarks on invalid input should be somewhere
> as an addition, not in the main entry. The negative value for interior
> ring, it is normally not called or encountered by end users. So it is
> also a detail, can go somewhere below in a section called e.g. "details"
> or so.

Good point, I'll add a small section called Remarks or Details

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