On Sat, 20 Apr 2013 14:27:12 +0600, Stefan Behnel <stefan...@behnel.de>
wrote:
Nikita Nemkin, 20.04.2013 09:11:
On Sat, 20 Apr 2013 02:11:21 +0600, Stefan Behnel wrote:
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.
I honestly didn't expect random string literals in the middle of
the class. Adding an extra test is never a problem.
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.
Very unlikely and very minor documentation(!) errors.
Wrong docstring on a property descriptor, couldn't be any more harmless.
I don't think "bad syntax leads to errors" argument holds 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)
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/
PEP362 is irrelevant for properties and attributes. Anyway, I was just
listing technicals problems biting autodoc users.
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.
I did document them manually at first. It is ugly (function doc in one
place,
attribute doc in another) and it does not work well with autodoc and
autosummary (no summaries for attributes, attrbute section appears in the
wrong place and other "minor" problems that require heavy Sphinx hacks to
get around.) All in all, it completely defeats the purpose of AUTOdoc.
The practice of autodocumentation is widespread in Python
(docstrings are a part of the language semantics) and I'd rather it
support properties and attributes without messy workarounds.
Sphinx has some way to go in this area, but putting strings
into __doc__ slots is Cython's responsibility.
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.
It does not change the language syntax one bit, it just adds a semantic
on top, like all docstrings do. Think of it this way:
cdef public/readonly is a shorthand for a complete property declaration.
Similarly, attribute docstring is a shortcut for providing a __doc__
for this property. PEP258/Sphinx/epydoc already have an established
convention for such docstrings, we just put these pieces together.
A mention that a docstring can be provided for a cdef public attribute
is all "exposure" it needs. Those who don't need/don't know about it
won't be affected.
Best regards,
Nikita Nemkin
_______________________________________________
cython-devel mailing list
cython-devel@python.org
http://mail.python.org/mailman/listinfo/cython-devel
