Nikita Nemkin, 20.04.2013 09:11: > On Sat, 20 Apr 2013 02:11:21 +0600, Stefan Behnel 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?
Well, once there is a docstring, that factor goes down to at most 3x. It's not entirely overkill, although I agree that it's definitely way more complexity than just adding a docstring. > PEP 258 was rejected, but Sphinx supports it, an so does epydoc. That makes it more reasonable then, but see below. >> 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. I can't see that from the tests you wrote. > Also, internal comments in the middle of the class are not usually > put into strings, actual comment syntax is more appropriate here. The less common it is, the more likely it is to be a source of confusion when it happens. And the proposed syntax is definitely prone to errors that go undetected. > 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) It's not more than a clumsy work-around for the CPython quirk that C implemented functions couldn't expose their signature. And that problem is much better tackled by completing the support for PEP 362. http://www.python.org/dev/peps/pep-0362/ > 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. The way I see it, if the embedsignature feature actually died because of PEP 362, you could just document attributes yourself without having Cython interfere with it at all. And AFAIU, that would solve most of your above problems. > 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.) It's not about the implementation. The question is if this feature should become part of the language because it's "special enough to break the rules" of OOTDI and if so, how we should expose it. And yes, that's a wonderful field for bike shedding. Stefan _______________________________________________ cython-devel mailing list cython-devel@python.org http://mail.python.org/mailman/listinfo/cython-devel
