Sign in Join

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

Mailing lists / lazarus / 2011-09

Overloaded procedures

4 messages · 3 people · –

Reply by email Subscribe to this list Your subscription

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

Martin
to Hans-Peter Diettrich: In my attempt to update the LCL documentation I came across overloaded procedures, like…
Hans-Peter Diettrich wrote 11 lines
In my attempt to update the LCL documentation I came across overloaded procedures, like DbgS, with arguments of different type but same name. This disallows to document the procedures properly :-( FPDoc creates only one entry for overloaded procedures (in the same unit), and lists all declarations there. Since only one description can be given, the parameters can be documented only in the declarations, and only if they have different names. Please watch for overloaded procedures, and use unique parameter names for every type.

You might have a point with a need for the feature...

Though it may be argued that if 2 (or more) overloaded function, are so differnet, that they need 2 documentations, then thye should be given different names rather than being overloaded (of course not helpful to the documenter, who can not change the problem.

Anyway, I do NOT wish to discourage, the potential use of such a feature. But I do hope you picked a bad example?

"dbgs" has maybe 20 different versions? Do you really want 20 different doc entries? IMHO that would make the doc far harder to read?

All dbgs do the same thing. Take an argument (which can be of one, of a list of types) and return a string, that can be used for logging in debug-logs.

The only thing that may differ, is the example of the actual returned text. If one wants to include the example. But IMHO it is better to list all examples on a single doc entry. From a user who needs to look it up, it is much quicker to find.
Searching for "dbgs" (if each entry has a page) does not know the type yet. So it could only diplay a list of all entries, and make the user chose => but that means even to get the basic info (which equals for all entries) needs an extra step.

Reply by email

Hans-Peter Diettrich

In my attempt to update the LCL documentation I came across overloaded procedures, like DbgS, with arguments of different type but same name. This disallows to document the procedures properly :-(

FPDoc creates only one entry for overloaded procedures (in the same unit), and lists all declarations there. Since only one description can be given, the parameters can be documented only in the declarations, and only if they have different names.

Please watch for overloaded procedures, and use unique parameter names for every type.

DoDi

Reply by email

Hans-Peter Diettrich
to Martin: You might have a point with a need for the feature... Though it may be argued that if 2…
Show quoted text 14 lines
On 17/09/2011 16:00, Hans-Peter Diettrich wrote: > In my attempt to update the LCL documentation I came across overloaded > procedures, like DbgS, with arguments of different type but same name. > This disallows to document the procedures properly :-( > > FPDoc creates only one entry for overloaded procedures (in the same > unit), and lists all declarations there. Since only one description > can be given, the parameters can be documented only in the > declarations, and only if they have different names. > > Please watch for overloaded procedures, and use unique parameter names > for every type. You might have a point with a need for the feature...

I don't see what here could be turned into a new feature?

Anyway, I do NOT wish to discourage, the potential use of such a feature. But I do hope you picked a bad example?

A non-standard example, may be.

"dbgs" has maybe 20 different versions? Do you really want 20 different doc entries? IMHO that would make the doc far harder to read?

I don't want to change the doc generation, only the declarations in source code. Perhaps you didn't notice what FPDoc really does, due to the lack of parameter descriptions in the XML files. But once the parameters have (at least short) descriptions, these are shown with the parameter of the same name, in the generated docs. Try yourself :-)

All dbgs do the same thing. Take an argument (which can be of one, of a list of types) and return a string, that can be used for logging in debug-logs.

Right, DbgS is quite a special example. Nonetheless a user may be interested in learning more about the available versions - that's what documentation is made for. E.g. what's the output format for a TRect...

DoDi

Reply by email