[Cython] Autodoc improvements (#216)

[Nikita Nemkin]

On Sat, 20 Apr 2013 17:41:56 +0600, Stefan Behnel <stefan_ml at behnel.de>  
wrote:

> Nikita Nemkin, 20.04.2013 12:43:
>> On Sat, 20 Apr 2013 14:27:12 +0600, Stefan Behnel wrote:
>> I did document them manually at first. It is ugly (function doc in one  
>> place,
>> attribute doc in another)
>
> As it should be. The attributes are part of the class documentation,
> whereas the function/method documentation belongs to the functions. I  
> can't
> see why you consider this totally normal distinction "ugly".

Why should attributes and especially properties (class members) be treated
differently from methods (class members) for documentation purposes?
 From the OOP standpoint they certainly should not. Smalltalk and Java are
good examples. (Smalltalk even has a documentation convention extremely
similar to Python docstrings.)

> All I'm saying is that docstrings for cdef attributes are a very special
> case. If you had a Python class in a Cython module, you couldn't add a
> docstring to its attributes at all. And there already is a dedicated  
> syntax
> for non-trivial properties in cdef classes. So the question is: is a
> property with a docstring still a trivial property or not? And is the use
> case common enough to complicate the simple special case that already
> exists, even though the completely general case can already be handled?

"cdef public" is one of the two forms of property declaration in Cython.
(The other being "property: ...") Both use nonstandard Python syntax and
neither seems a "special case" to me.

The property is trivial iif its code consists of one __get__
function with "return self.value" body. What does docstring have to do
with it?
"property:" is not completely general. I wont rename every
single public attribute for the privilege of attaching a docstring
to it (and a ton of boilerplate code). It makes no sense from
technical and maintenance standpoint.

Considering use cases. Currently I have 83 cdef public/readonly attributes
across 46 classes that represent ~20% of the source codebase.
All of them have docstrings (since they are public and part of the API.)

This feature is very low impact to worry about added complexity.

>>>> 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
>
> I didn't say it would change the syntax. It changes the semantics of a
> string that follows an attribute declaration (for whatever reason) and
> makes strings that appear after such declarations the official One Right
> Way to document cdef attributes, i.e. a Cython language feature.

Since there are currently Zero Right Ways to document these attributes,
having at least one is a good thing.
"property:" form is not diminished by that, in cases _when it is  
warranted_.

> BTW, the pure Python mode doesn't currently have this feature either, it
> seems. (I'm not even sure it has public/readonly attributes...)

Pure python mode project can be processed by Sphinx like any ordinary
Python project, with complete support for all autodoc features.

Since Python level attributes have no __doc__ slots, there is nothing
Cython can do with their docstrings anyway (except parsing them without
syntax errors).

>> 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.
>
> ISTM that there is more than one convention:
>
> http://sphinx-doc.org/ext/autodoc.html#directive-autoattribute

Other conventions? Do you mean "#:" comments? These forms are not part of
PEP258, can't be paralleled to the "property:" syntax and require too many
changes to Cython lexer and parser for no extra benefit.
Therefore I have not implemented them.

> But the newer one apparently uses the docstring syntax (which IMHO makes
> way more sense than special casing comments).

Exactly.

>> 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.
>
> Except by accident, as I said. Users of Sphinx *may* be aware of this,
> others most likely won't be.

In the worst case, probability of which is near zero, the unsuspecting
victim will waste a few bytes of memory (the size of the comment).
This is a non-issue.


Best regards,
Nikita Nemkin