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

[michael.vancanneyt at wisa.be]

On Fri, 6 Jan 2012, dhkblaszyk at zeelandnet.nl wrote:

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

Correct.

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

Indeed. What version of fpdoc are you using ?

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

This is very good.

>> 2) The result types are also
> put in a result table (needs modification in the XML as described above)

I don't think this is good. The XML elements are name based, lookups are 
or can be done on name only.

>> 3) initialized variables (style: integer = 0) are automatically
> added to the description eg (default = 0)

I think this is redundant information because it
a) appears in the declaration
b) can be mentioned in the short description.
But it can definitely be an option: --document-argument-defaults

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

I will not discuss taste, but what if there are references in the short description ? 
You can't nicely handle that in comments, so I think this should be an option as
well: --document-arguments-inline

Michael.