[Cython] Autodoc improvements (#216)

[Nikita Nemkin]

On Sat, 20 Apr 2013 14:27:12 +0600, Stefan Behnel <stefan_ml at 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