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

Subject: [ggl] [doc] Index template parameters for get/set accessors?
From: Barend Gehrels (Barend.Gehrels)
Date: 2010-03-09 03:57:01

Hi Mateusz,

> 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 agree, it is better to solve it properly.

>   
>> 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.
>   
The new approach sounds very good.
But do you really generate a page per function overload? For this 
specific situation, I agree. However, for e.g. the area algorithm, 
having two overloads, one with a strategy and one without, is it not 
cleaner to present them together? Or "intersection" and 
"intersection_inserter"? Or the overloads in different namespaces which 
we will get?

However, I understand that this will have some technical implications.

> Thus, I think it is better to document actual parameters of given
> function next to that function, instead of manually outsmart Doxygen.
>   

I agree.

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

Agreed.

Regards, Barend

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