[Lazarus] Overloaded procedures
DrDiettrich1 at aol.com
Sat Sep 17 23:22:36 CEST 2011
> 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
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...
More information about the Lazarus