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

Regards,
Darius

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.

Resending the email. The images are here:

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

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

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

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

Resending the email. The images are here:

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

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

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

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

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

Correct.

Indeed. What version of fpdoc are you using ?

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

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.

In our previous episode, 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.

Regards, Darius

In our previous episode, said:

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

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.

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.