Geometry Boost List: [ggl] [doc] Index template parameters for get/set accessors?

Subject: [ggl] [doc] Index template parameters for get/set accessors?
From: Mateusz Loskot (mateusz)
Date: 2010-03-08 16:01:52

Barend Gehrels wrote:
> Mateusz Loskot wrote:
>> Mateusz Loskot wrote:
>>  
>>> For get/set functions in access.hpp, there is template parameters Index
>>> documented but none of the get/set prototypes make use of it.
>>>
>>> For example, get function
>>>
>>> template <std::size_t Dimension, typename Geometry>
>>> inline typename coordinate_type<Geometry>::type get(
>>>   Geometry const& geometry)
>>>
>>> has the following bit in its doxygen comment:
>>>
>>> \tparam Index index
>>> - for Point: don't specify
>>> - for Box: min_corner or max_corner
>>> - for Segment: 0 / 1
>>>
>>> Is this doc out of sync or the Index is there on purpose?
>>     
>>
>> OK, I think I find what's going on.
>> The Index is documented for wrong get/set versions.
>> So, the fix is just to shuffle the comments to right places.
>
>   
> Something like this is going on indeed, but it is actually not wrong or
> shuffled but on purpose.
>
> What is happening is that all is documented for a generic "get" function
> (http://geometrylibrary.geodan.nl/group__access.html#g369b4a9519f357a05b68739fcf4ab374)
> but behind the scenes it is splitted in two separate get functions, one
> for points (with one template parameter: dimension), one for
> boxes/segments (with two template parameters: Dimension/Index).

I see. It is confusing because the prototype of the function does not
specify all the parameters which are documented in that place,
so I got suspicious something is wrong.

> I'm curious if shuffling will solve it in the new approach, because
> (IIRC) Doxygen was not too happy with this construction of two overloads
> with different template parameters.

I'm not sure what you mean by "Doxygen was not happy", but in the new
approach we're parsing XML output directly and on our own, using XSLT,
so we have access to all details. Meaning, I'm trying to generate
separate page per a function overload.
Thus, I think it is better to document actual parameters of given
function next to that function, instead of manually outsmart Doxygen.
Otherwise, a separate HTML page for particular overloaded version of a
function will present irrelevant information.

Nevertheless, let's not make any cross-project changes to the comments
until I finish crafting XSL sheet and confirm any changes are needed at all.

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