Description
When creating a Python class, if I put docstrings under the class name or under __init__
, these would show up, respectively, under class.__doc__
and class.__init__.__doc__
, e.g.:
class cl:
"""ds1"""
def __init__(self, a=1):
"""ds2"""
self.a = a
cl.__doc__ == "ds1"
cl.__init__.__doc__ == "ds2"
Usually, documentation is picked by other tools from the __init__
part, so that's where it's usually put, and in such case class.__doc__
will be empty (Python None
).
But with Cython classes having embedded signatures, if I put a docstring under __init__
, it will still generate a non-empty class.__doc__
, which will contain the function arguments but not the rest, e.g.
cimport cython
@cython.embedsignature(True)
cdef class cl:
cdef int a
def __init__(self, a = 1):
"""ds"""
self.a = a
cl.__doc__ == "cl(a=1)"
cl.__init__.__doc__ == "ds"
(And if I don't put it, it wouldn't document the arguments)
Would be nice if documentation would work the same as in regular Python (i.e. don't create class.__doc__
if the docstring is under __init__
), as it makes it easier for the documentation to work with other tools. For example, sphinx will by default look for __doc__
first, so in this case it ends up (by default) showing only the function call documentation and not the user docstring.