Group arguments from overloaded functions in fpdoc

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

Group arguments from overloaded functions in fpdoc

Darius Blaszyk

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?

More importantly, would a patch of this sort be approved? Can the authorities comment on this please? Knipogen

 

Regards, Darius

 

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Group arguments from overloaded functions in fpdoc

Michael Van Canneyt


On Thu, 5 Jan 2012, [hidden email] wrote:

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

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Group arguments from overloaded functions in fpdoc

Darius Blaszyk

Resending the email. The images are here:

 

http://imagebin.org/192019

http://imagebin.org/192020

http://imagebin.org/192021

 

On 6 jan '12, [hidden email] wrote:

I checked doxygen (http://www.stack.nl/~dimitri/doxygen/examples/overload/html/class_test.html#a8e7b46ceaf7bd2ab94114b390b3288ca), 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)

 

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. 

 

 

 

 

 

 

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Group arguments from overloaded functions in fpdoc

Darius Blaszyk
In reply to this post by Michael Van Canneyt

Resending the email. The images are here:

 

http://imagebin.org/192019

http://imagebin.org/192020

http://imagebin.org/192021

 

On 6 jan '12, [hidden email] wrote:

I checked doxygen (http://www.stack.nl/~dimitri/doxygen/examples/overload/html/class_test.html#a8e7b46ceaf7bd2ab94114b390b3288ca), 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)

 

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. 

 

 

 

 

 

 

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Group arguments from overloaded functions in fpdoc

Michalis Kamburelis-3
In reply to this post by Darius Blaszyk
[hidden email] wrote:
> 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).

As for pasdoc:

PasDoc currently doesn't group overloaded functions in any way for
display. They are just treated like two (or more) separate functions.
Yeah, this sucks, I agree. Everyone is welcome to submit feature
requests and, even better, patches of course :) I had a plan to
implement one day "grouping", so that a group of identifiers can be
nicely displayed together with a single description (this could be used
for overloaded functions, and also for explicitly marked groups by
@groupXxx tags, see
http://pasdoc.sipsolutions.net/MichalisKamburelis#Support_for_groups_of_items 
). This is probably the most important missing pasdoc feature for me
personally, but still there's never time to implement it.

Michalis
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Group arguments from overloaded functions in fpdoc

michael.vancanneyt
In reply to this post by Darius Blaszyk


On Fri, 6 Jan 2012, [hidden email] 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,
> [hidden email] 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.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Group arguments from overloaded functions in fpdoc

Marco van de Voort
In our previous episode, [hidden email] 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
 
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Group arguments from overloaded functions in fpdoc

Darius Blaszyk
> In our previous episode, [hidden email] 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.

Regards, Darius

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Group arguments from overloaded functions in fpdoc

Marco van de Voort
In our previous episode, [hidden email] said:

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

The result-type is not enough to disambiguate overloaded versions. You would
need a full signature.

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Group arguments from overloaded functions in fpdoc

Darius Blaszyk
> In our previous episode, [hidden email] said:
>> > 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.
>
> The result-type is not enough to disambiguate overloaded versions. You
> would
> need a full signature.

You're right. We could calculate the checksum of the function declaration
section and use that as a unique identifier.

Darius

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Group arguments from overloaded functions in fpdoc

michael.vancanneyt
In reply to this post by Darius Blaszyk


On Fri, 6 Jan 2012, [hidden email] wrote:

>> In our previous episode, [hidden email] 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.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Group arguments from overloaded functions in fpdoc

Michael Van Canneyt


On Fri, 6 Jan 2012, [hidden email] wrote:

>
>
> On Fri, 6 Jan 2012, [hidden email] wrote:
>
>>> In our previous episode, [hidden email] 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.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal