On Sat, 20 Apr 2013 02:11:21 +0600, Stefan Behnel <stefan...@behnel.de>
wrote:
Nikita Nemkin, 18.04.2013 07:07:
2) Public/readonly cdef attributes can have docstrings attached, using
the [PEP 258 attribute docstring
syntax](http://www.python.org/dev/peps/pep-0258/#attribute-docstrings).
Example:
cdef class X:
cdef public attr
"""attr docstring"""
When ``embedsignature=True`` Cython already adds a signature docstring
to the generated property (assuming the example above). This patch
allows to add an actual docstring too.
Dosctrings on private cdef attributes will give a warning
("docstring ignored").
Other forms and uses of attribute docstrings, as described in the PEP
258, are not supported at all (SyntaxError), because there is no
standard introspection mechanism designed for them. ([PEP
224](http://www.python.org/dev/peps/pep-0224/) describing such
mechanism had been rejected.)
Worth noting that PEP 258 was rejected, although definitely for other
reasons than this feature. I remember discussing this topic before on the
mailing list, but don't remember if we reached a conclusion. I faintly
recall that we preferred making the property explicit as soon as there's
more to it than a plain 1:1 mapping to the cdef attribute.
Separating property from the attribute requires mass renaming of
the attribute (as was recently descussed here) and bloating the code x4.
All this just to attach a docstring?
PEP 258 was rejected, but Sphinx supports it, an so does epydoc.
The need to autodocument attributes remains.
The above syntax is not wrong, but it also doesn't feel right to me. For
example, it's impossible to draw a distinction between the above and
something like
cdef class X:
cdef public attr
"""
quotes used for commenting out code here.
"""
And users are unlikely to notice that they just dropped some internals
into
the docstring of a property they didn't even know they were implementing.
IMHO, the user intention is way too unclear in this syntactic construct.
Attribute docstring must appear immediately after the attribute. The extra
blank line in your example makes the string standalone, just as you
intended.
Also, internal comments in the middle of the class are not usually
put into strings, actual comment syntax is more appropriate here.
Documenting attributes manually, for example, with ".. attribute"
directives in the class docstring or .rst file, creates the following
problems:
1) In embedsignature mode (which is almost mandatory for a decent autodoc)
Cython adds signature docstrings to public attributes,
making them appear twice: one instance with a manually written doc,
another instance with a signature docstring.
2) Manually documented attributes don't follow autodoc settings
(ordering, formatting). They are also invisible to autosummary
and other extensions.
3) (Obviously) non-uniformity between property, function and attribute
documentation practice.
Attribute docstrings are the cleanest solution to all of these problems.
And the patch is just a few lines (if you discount the refactoring of the
"XXX This should go to AutoDocTransforms" block.)
Best regards,
Nikita Nemkin
_______________________________________________
cython-devel mailing list
cython-devel@python.org
http://mail.python.org/mailman/listinfo/cython-devel
