On Jul 12, 2006, at 10:53 AM, Barry Warsaw wrote:
>> In any case, allowing the constructor signature to be expressed in
>> class docstring seems reasonable. I saw the same convention used
>> somewhere, just as the object __init__ docstring suggests.
> I think this /is/ a problem for extension types. The constructor for
> an extension type is defined in the tp_init slot of the type struct
> and the struct's tp_doc slot is the only place that you can hang
> documentation. AFAICT this slot really serves dual purposes as both
> the type's (a.k.a. class's) documentation and the documentation for
> the constructor.
Ah, I hadn't realized that there was no way to give the class & the
constructor separate docstrings for extension classes. In that case,
this definitely should be supported. I.e., epydoc should check the
class docstring to see if it starts with a signature-like line, and
if so, derive the constructor signature from it, and create a new
documentation entry for the constructor. This should probably only
be done for builtin/extension classes, not pure python classes.
Unfortunately, I won't have time to work on this for a little while.
But if anyone wants to put together a patch to do this (for epydoc 3,
or 2, or both), that would be great! :)
> BTW, I tried Edward's suggestion in my tp_doc docstring and it
> doesn't really work. The class documentation stops at the first
> @param and AFAICT just gets thrown away.
I was assuming that the constructor had its own docstring, just like
other methods. If that's not the case, then this won't work. :)