Geometry Boost List: [ggl] [doc] New draft of Reference based on Doxygen-to-Boostbook

Subject: [ggl] [doc] New draft of Reference based on Doxygen-to-Boostbook
From: Barend Gehrels (Barend.Gehrels)
Date: 2010-03-17 12:15:35

Hi Mateusz,

Thanks. As mentioned over GT, it's getting better each time :-)

>   
>> There is some functionality which is not yet there:
>>
>> - compare
>>     
>
> Done, but without two files:
> intersection_points.hpp
> intersection_points_determinant.hpp
> I'm not sure why, but Doxygen fails to generate valid XML if these
> files are included in input.
>   
OK, strange indeed.

>   
>> (equal_to, greater, less) which are not algorithms but policies which 
>> can be used for std::functions like unique and sort
>>     
>
> I added Policies section between Algorithms and Strategies.
> Perhaps they should go below Strategies.
>   
Fine for me. The separation between policy and strategy is sometimes 
vague, maybe we have to discuss this further.

> Actually, firstly I wanted to keep order of the major sections
> according to "from simple building blocks, to complex combinations:.
> IOW, in order of how elements are being combined together.
>
> Though now, after I've added load more of elements, I'm getting lost on
> how to logically arrange the table of content (ToC) to make it
> intuitive, to make it introducing the library gradually, etc.
>   
I see. Actually all are building blocks. Geometries, algorithms, 
strategies, policies. You might see algorithms as the most complex 
combinations. But these things are the first things that users will use...

>>     
>
> I am going to document the extensions in similar way.
> I mean, officially accepted exceptions.
> I prepared section for extensions but it's empty now.
> Perhaps, table of contents of extensions reference should be on
> separate page?
>   
Yes, fine for me, and it is maybe a good idea to have two reference 
pages for accepted and non-acccepted extensions. We have still to 
formalize this anyway.
>   
>> There are some functions that I doubted recently if they are on the
>>  
>> right place in core, and these are: num_points, num_interior_rings. Now 
>> that I see them there, those are not really Access functions but more 
>> utilities, they probably can be moved to Algorithms if there are no 
>> objections.
>>     
>
> Yes, I have similar impression, though, I'm not sure if they
> belong to Algorithms. Perhaps a separate category Utilities for
> such general purpose tools?
>   
Yes. There is a utilities too.
But some are OGC prescribed...

> Initially, I was thinking of "Loop" to keep more descriptive
> headers than named after functions.
>   
Maybe. We had a function called Loop before but it is obsoleted now (and 
removed). Maybe foreach is not so bad (the underscore is a nuisance, 
std::for_each has it, BOOST_FOREACH does not..

>
>
> So, should I move them to Overlay?
>   
OK
>   
>> Maybe we can group assign, append and clear together, they actually
>> form a sort of group together with make.
>>     
>
> I agree, they belong to same category. They feel more like
> connected with Geometry Constructors.
> What about moving them below the Constructors to category called
> like  Geometry Modifiers?
>   
Good idea, fine for me.

>
>   
>> If this all is the case we can restructure the arithmetic, because 
>> dot/cross are more or less redundant, add_value etc also, add_point 
>> would be add_vector_to_point (or something like that, or not be renamed but 
>> restructured internally).
>>     
>
> What about supporting keeping both approaches, point-based and vector-based?
>   
Yes, that is certainly possible too... have to think about this.

Regards, Barend

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