[Lazarus] Overloaded procedures

[Hans-Peter Diettrich]

Martin schrieb:
> 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