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

[michael.vancanneyt at wisa.be]

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

>> In our previous episode, michael.vancanneyt at wisa.be said:
>>>>> 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.
>>
>> See also
>> http://bugs.freepascal.org/view.php?id=14843
>>
> Could XML attributes be used to distinguish overloaded functions? eg
>     <element name="UIContext.doButton.Result">
>        <short result="boolean">boolean result</short>
>        <short result="integer">integer result</short>
>      </element>
>
> It should be relatively easy to implement I presume, not break any
> existing documentation and it would solve the overload problem.

All code assumes 1 short tag, a reference to it is stored for speed in
DocNode.

I don't really regard this as a problem. In cases where the result really
is something else (I assume this will be a minority, seeing that I've never
encountered one, and I've documented many units) you can perfectly put

<element name="UIContext.doButton.Result">
<short>An integer with return status or boolean with the result of the operation</short>
</element>

to solve the "problem".

An identical problem exists for the parameters, if they have the same name.

The single arguments table with one entry per named argument is already a
huge step forward, IMHO, and sufficient to cover most needs. The function
description can be used to elaborate the subtle differences, if the need is there.

Michael.