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

[Barry W. <ba...@py...>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Jul 12, 2006, at 12:43 PM, Daniele Varrazzo wrote:

> The string
>
>    x.__init__(...) initializes x; see x.__class__.__doc__ for  
> signature
>
> is just "object.__init__" docstring. Actually this is in contrast with
> PEP 257, which informs:
>
>   The class constructor should be documented in the docstring for its
> __init__ method.
>
> Epydoc treats __init__ as a normal method (at least from this PoV):
> the ctor parameters should be added to the __init__ docstring.
> Example:
>
>    class Foo(object):
>        """This is the object signature"""
>        def __init__(self, a, b):
>            """The ctor.
>
>            @param a: The first letter
>            @type a: int
>            @param b: The letter after the first
>            @type b: str
>            """
>            pass
>
> Is this a problem for extension types? I guess the __init__.__doc__
> can be customized.
>
> @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.  There is really no other place to tie documentation  
to an extension type's __init__(), unlike for other methods which are  
defined in a PyMethodDef containing slots for both the function and  
docstring.

So it seems like parsing constructor signatures out of a class  
docstring for extension types is the only option.

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.

- -Barry

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (Darwin)

iQCVAwUBRLUo7HEjvBPtnXfVAQIudgQAkm6piVS/81fYStQyST9AqTWr+UCPg/EN
jq7g0SbNOjqHM4ZztfS9iRH9FBgb/B2WDHPexgRmvVSowgBhBdADBHWS529A0voq
8mW/u9QCYf4PrHoU0GyF3hn9iBfe/egXIt7xdF+Kb9t1su/WCPqM9Aoxk1qzLR7h
NxGBaxR1NpE=
=BTOB
-----END PGP SIGNATURE-----