FPDoc - how to document overloaded functions?

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

FPDoc - how to document overloaded functions?

Graeme Geldenhuys-6
Hi,

How do you document overloaded functions? In this case I have overloaded
functions that have different parameters (obviously), but also different
result types.


I've been looking through the FPDoc PDF manual, but there is no explicit
information on this subject. But then, I could be overlooking something
(it happens).

Regards,
   Graeme

--
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

My public PGP key:  http://tinyurl.com/graeme-pgp
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: FPDoc - how to document overloaded functions?

Michael Van Canneyt


On Wed, 12 Jul 2017, Graeme Geldenhuys wrote:

> Hi,
>
> How do you document overloaded functions? In this case I have overloaded
> functions that have different parameters (obviously), but also different
> result types.

You can't. There are no provisions for this.

I usually make the differences clear in the <descr> </descr> node.

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

Re: FPDoc - how to document overloaded functions?

Graeme Geldenhuys-6
On 2017-07-12 15:06, Michael Van Canneyt wrote:
> You can't. There are no provisions for this.
>
> I usually make the differences clear in the <descr> </descr> node.


Thanks Michael. I've been playing around with fpdoc and trying a few
things and then reviewing the results. Attached is the output I have
thus far for ovorloaded functions.

NOTE:
   In generates multiple "Arguments" sections, and they seem to appear
   in the same order as what they are in the "Declaration" section.
   I only documented each parameter once in the XML, and fpdoc
   duplicated it to match the Declaration section.

   It kind of works, but there is definitely place for improvement in
   the HTML output (layout of information).


ps #1:
   I haven't tried documenting function results yet, so not sure what
FPDOC is going to do with that in this output.


ps #2:
   Also not the "Errors" section. There I simply used the <p> tags to
document both possible error results. I couldn't see any other way of
doing it.

Regards,
   Graeme

--
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

My public PGP key:  http://tinyurl.com/graeme-pgp

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

shot.png (61K) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: FPDoc - how to document overloaded functions?

Graeme Geldenhuys-6
On 2017-07-12 15:19, Graeme Geldenhuys wrote:
> ps #1:
>    I haven't tried documenting function results yet, so not sure what
> FPDOC is going to do with that in this output.


I had a look at documenting function results. There seems to be a bug
(or place for improvement) in the HTML output. Even worse, the Linear
output writers don't output Arguments at all! :-/

Back to the HTML output. Using the 4 overloaded FileAge functions, the
output is as follows:

   Declaration
      // lists all 4 overloaded functions here
   Arguments
      // ...
   Function result
      // ...
   Arguments
      // ...
   Arguments
      // ...
   Arguments
      // ...
   Description
      // ...


As you can see, the "Function result" section only appears once, and
only after the first "Arguments" section. I'm thinking the best place
would rather be to list all 4 "Arguments" sections, then followed by the
"Function results" section.

Alternatively, I can try listing one "Argument", then one "Function
result", repeat. I'm not sure if this is possible though, and what
happens if one of the overloads don't actually have a result.

Your thoughts?

ps:
   I can send you a screenshot in private if that will help visualise
   things better. The FPC mailing list doesn't seem to like attachments
   at all.



Regards,
   Graeme

--
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

My public PGP key:  http://tinyurl.com/graeme-pgp
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: FPDoc - how to document overloaded functions?

Michael Van Canneyt
In reply to this post by Graeme Geldenhuys-6


On Wed, 12 Jul 2017, Graeme Geldenhuys wrote:

> On 2017-07-12 15:06, Michael Van Canneyt wrote:
>> You can't. There are no provisions for this.
>>
>> I usually make the differences clear in the <descr> </descr> node.
>
>
> Thanks Michael. I've been playing around with fpdoc and trying a few things
> and then reviewing the results. Attached is the output I have thus far for
> ovorloaded functions.
>
> NOTE:
>  In generates multiple "Arguments" sections, and they seem to appear
>  in the same order as what they are in the "Declaration" section.
>  I only documented each parameter once in the XML, and fpdoc
>  duplicated it to match the Declaration section.
>
>  It kind of works, but there is definitely place for improvement in
>  the HTML output (layout of information).
>
>
> ps #1:
>  I haven't tried documenting function results yet, so not sure what FPDOC is
> going to do with that in this output.
>
>
> ps #2:
>  Also not the "Errors" section. There I simply used the <p> tags to document
> both possible error results. I couldn't see any other way of doing it.

I'm not sure I understand what you're trying to achieve ?

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

Re: FPDoc - how to document overloaded functions?

wkitty42
On 07/13/2017 06:30 AM, Michael Van Canneyt wrote:
> I'm not sure I understand what you're trying to achieve ?


@graeme: maybe you could mock up what you are wanting/expecting from this
particular situation? that way we (TINW) could compare the two and see the
difference??


--
  NOTE: No off-list assistance is given without prior approval.
        *Please keep mailing list traffic on the list unless*
        *a signed and pre-paid contract is in effect with us.*
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Loading...