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

Subject: [ggl] [quickbook] Algorithms quickbook sample
From: Barend Gehrels (Barend.Gehrels)
Date: 2010-02-14 14:10:25

Hi Mateusz,

>   
>> Question: why are the tables numbered? Is that everywhere?
>>     
>
> The table number seems to be generated automatically, see Fusion docs
> for instance:
>
> http://www.boost.org/doc/libs/1_42_0/libs/fusion/doc/html/fusion/iterator/functions/deref.html
>   
OK, I see.

>   
>> I just also checked the perfect cplusplus reference, e.g.
>> http://www.cplusplus.com/reference/algorithm/min/,
>>     
>
> I've experienced errors on this website.
> Personally, I prefer to rely on the C++ standard.
>   
Good to know.
>   
>> 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.:
>>     
>
> I decided to distinguish following other Boost docs as examples,
> for instance Fusion:
>
> http://www.boost.org/doc/libs/1_42_0/libs/fusion/doc/html/fusion/view/single_view.html
>   
>>
>> 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?

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

>   
>> Question: the synopsis is missing the typename keyword, is that on
>> purpose?
>>     
>
> I copied the prototype as it is presented by the Doxygen-based
> reference:
>
> http://geometrylibrary.geodan.nl/group__area.html
>
> The typename should be included, so I've fixed it in *.qbk
> file in SVN.
>   
Hey, I didn't catch that at that time. Doxygen must omit them. So yes, 
good to include them, thanks.

>   
>> You suggested that the performance section will be replaced with
>> complexity so I think that still is to be done. 
>>     
>
> Yes, IMHO complexity is a better name.
> Performance may suggest that this is about benchmarking, but it is not
> supposed to be. It is about explaining computational complexity
> guarantees and requirements, not about benchmarking.
>   
Yes, I agree
> Actually, I'm unsure about including any timing in this section, but
> just raw complexity detail.
>   
So yes, they may be deleted here.

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

Regards, Barend

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