Re: [Epydoc-devel] __init__ params for extension type?

[Edward L. <ed...@gr...>]

On Jul 12, 2006, at 10:53 AM, Barry Warsaw wrote:
>> @Edward:
>> In any case, allowing the constructor signature to be expressed in  
>> the
>> 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. :)

-Edward