[Lazarus] Overloaded procedures

[Martin]

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

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.