Sign in Join

Live chat for Free Pascal, Lazarus, Delphi and every Pascal programmer.

Mailing lists / fpc-pascal / 2006-09

fpdoc and overloaded functions.

4 messages · 2 people ·

Reply by email Subscribe to this list Your subscription

Read-only archive. Use j and k to move between messages.

Graeme Geldenhuys

Hi,

What is the best way to document overloaded functions using fpdoc?

For example, I have a Find function which has been overloaded four times with different parameters. Looking in the generated *.xml file, I only have one Find element, followed by all the different parameters, each in there own element node.

In my previous documenting system, I had a different description for each Find method. With fpdoc, I can only have one. I thought if I documented the parameters, the html output might be what I wanted, but it isn't.

See the link below to help explain what I mean:
http://opensoft.homeip.net/tiopf/tiobject/ttiobject.find.html

Problems:
1. How do I get a different description for each overloaded Find method.
2. Why is the title "Arguments" repeated. (Note I only documented the first two Find methods as an example). I normally don't document the functions, I rather mention them in the function description.
3. Is there no other way (html layout) so the arguments are easier to match there respected overloaded functions. Currently it is difficult to see what argument relates to what overloaded function.

Is there a FPC html doc possibly showing the correct / better way of documenting overloaded functions.

Regards,
- Graeme -

There's no place like 127.0.0.1

Reply by email

Graeme Geldenhuys
to Graeme Geldenhuys

I see FPC docs have the same issue...

For example: TypInfo.GetPropList
http://lazarus-ccr.sourceforge.net/docs/rtl/typinfo/getproplist.html

No easy way to document each overloaded method...

Regards,
- Graeme -

Graeme Geldenhuys wrote 37 lines
Hi, What is the best way to document overloaded functions using fpdoc? For example, I have a Find function which has been overloaded four times with different parameters. Looking in the generated *.xml file, I only have one Find element, followed by all the different parameters, each in there own element node. In my previous documenting system, I had a different description for each Find method. With fpdoc, I can only have one. I thought if I documented the parameters, the html output might be what I wanted, but it isn't. See the link below to help explain what I mean: http://opensoft.homeip.net/tiopf/tiobject/ttiobject.find.html Problems: 1. How do I get a different description for each overloaded Find method. 2. Why is the title "Arguments" repeated. (Note I only documented the first two Find methods as an example). I normally don't document the functions, I rather mention them in the function description. 3. Is there no other way (html layout) so the arguments are easier to match there respected overloaded functions. Currently it is difficult to see what argument relates to what overloaded function. Is there a FPC html doc possibly showing the correct / better way of documenting overloaded functions. Regards, - Graeme - -- There's no place like 127.0.0.1
There's no place like 127.0.0.1

Reply by email

Michael Van Canneyt
to Graeme Geldenhuys: What is the best way to document overloaded functions using fpdoc? For example, I have a…
Graeme Geldenhuys wrote 19 lines
Hi, What is the best way to document overloaded functions using fpdoc? For example, I have a Find function which has been overloaded four times with different parameters. Looking in the generated *.xml file, I only have one Find element, followed by all the different parameters, each in there own element node. In my previous documenting system, I had a different description for each Find method. With fpdoc, I can only have one. I thought if I documented the parameters, the html output might be what I wanted, but it isn't. See the link below to help explain what I mean: http://opensoft.homeip.net/tiopf/tiobject/ttiobject.find.html Problems: 1. How do I get a different description for each overloaded Find method.

You can't.

2. Why is the title "Arguments" repeated. (Note I only documented the first two Find methods as an example). I normally don't document the functions, I rather mention them in the function description.

This is a bug; I should check that.

3. Is there no other way (html layout) so the arguments are easier to match there respected overloaded functions. Currently it is difficult to see what argument relates to what overloaded function.

Normally, the short description of the argument is displayed in the declaration of the function. This seems not to be so anymore, I will have to .

Reply by email

Graeme Geldenhuys
to Michael Van Canneyt
Michael Van Canneyt wrote
> Problems: > 1. How do I get a different description for each overloaded Find method. You can't.

Thinking about this, I guess it makes sense. In my case (and should apply to all overloaded methods) the Find function does the same thing, so that could be reflected in the single description available.

Normally, the short description of the argument is displayed in the declaration of the function. This seems not to be so anymore, I will have to noticed enumerated types do this, and look really nice. Having that

feature for overloaded functions should allow me to document the differences, and be easier to understand than having the argument listing only at the bottom.

Thanks Michael.

Regards,
- Graeme -

Reply by email