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

[Daniele V. <dan...@gm...>]

> Where would I document the parameters for extension types?  I thought
> I could add @param and @type fields to the docstring for the tp_doc
> slot, but when I generate the documentation I just get warnings like:
>
> In foo.Bar docstring:
>      - Warning: Invalid context for field tag 'param'
>
> In the generated documentation for the class's __init__() you see:
>
> x.__init__(...) initializes x; see x.__class__.__doc__ for signature
>
> but there appears to be no way to document that signature.  Or have I
> just screwed up somewhere? ;)

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.