[fpc-pascal] Group arguments from overloaded functions in fpdoc

[dhkblaszyk at zeelandnet.nl]

Resending the email. The images are here:


http://imagebin.org/192019 [3] 

http://imagebin.org/192020 [4]


http://imagebin.org/192021 [5] 

On 6 jan '12,
dhkblaszyk at zeelandnet.nl wrote: 

> I checked doxygen
(http://www.stack.nl/~dimitri/doxygen/examples/overload/html/class_test.html#a8e7b46ceaf7bd2ab94114b390b3288ca
[1]), but it does not seem to list the variables. Pasdoc does not seem
to group overloaded functions, but rather list them separate in a table
(http://pasdoc.sourceforge.net/autodoc/html/PasDoc_Gen.TDocGenerator.html#WriteConverted
[2]) 
> 
> On a side note, 
> 
> 1) for overloaded functions it seems
that only one result string is possible to define. As seen in the XML
file:(no desitinction based on result type) 
> 
> 2) string variables or
result types do not show in my documentation (as do more complex result
types as arrays, please look to the screenshots) seems to be a bug?? 
>

> Anyway, I have created a mockup for a slightly modified result from
fpdoc as seen in the screenshots. What has changed: 
> 
> 1) All
arguments are mixed into one table 
> 
> 2) The result types are also
put in a result table (needs modification in the XML as described above)

> 
> 3) initialized variables (style: integer = 0) are automatically
added to the description eg (default = 0) 
> 
> A second mockup adds the
argument and result type description as "comments" to the declaration
section. This eliminates the need to have a variable section completely.
It also adds the possibility to add different comments per overloaded
function even on variable level. Personally I like the comments approach
as it makes the documentation page nice and compact. 
> 
> Regards,
Darius 
> 
>>> When you have overloaded functions, fpdoc will group them
on one page. The arguments however are listed in two separate arguments
sections. It would be nice to have the arguments merged in one section.
I do not know how to display the arguments though (no idea what others
do like pasdoc or doxygen). Should only the unique arguments be shown
(perhaps sorted alphabetically?), should there be a table with arguments
per overloaded function?
>> 
>> It is already a table.
>> 
>>> More
importantly, would a patch of this sort be approved? Can the authorities
comment on this please? ;-)
>> 
>> If you find a nice solution: Of
course. Maybe a single table will be more clear. Function results may be
more difficult: Function A(b) : C; Function A(d) : E; But I agree that
the current situation is not ideal.

  

Links:
------
[1]
http://www.stack.nl/~dimitri/doxygen/examples/overload/html/class_test.html#a8e7b46ceaf7bd2ab94114b390b3288ca
[2]
http://pasdoc.sourceforge.net/autodoc/html/PasDoc_Gen.TDocGenerator.html#WriteConverted
[3]
http://imagebin.org/192019
[4] http://imagebin.org/192020
[5]
http://imagebin.org/192021
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freepascal.org/pipermail/fpc-pascal/attachments/20120106/7954884f/attachment.html>