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

[Michael Van Canneyt]

On Fri, 6 Jan 2012, michael.vancanneyt at wisa.be wrote:

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

Thinking about this, we can maybe do the following:

  <element name="UIContext.doButton.Result">
  <short>A short description</short>
  <overloads>
    <overload name="integer">
    <short>Short description for overload integer.</short>
    </overload>
    <overload name="boolean">
    <short>Short description for overload integer.</short>
    </overload>
  </overloads>
  </element>

This is 100% backwards compatible, and doesn't compromise on speed.

When the short description of UIContext.doButton.Result is needed,
the default one can be taken (if it is present), and if overloads 
are present, then the correct overload can be searched using the type name.

The reason for the '<overload>' tag is that at a later stage we may 
decide to add additional nodes to it.

In fpdoc's dglobals, we can add a

   Property HasOverloads : Boolean read GetHasOverloads;
   Property overloads : TFPList read FOverloads;

to TDocNode.

An option --handle-overload-type can then control how overloaded results are handled in HTML.

Michael.