[Cython] [cython] Autodoc improvements (#216)

[Stefan Behnel]

Nikita Nemkin, 18.04.2013 07:07:
> Three improvements are included in this patch that I have found helpful when using Sphinx autodoc to document my project:
> 
> 1) Default values preserve and display binary expressions and attribute access. For example, the following function will have its signature displayed as is:
>      
>     cpdef func(int flags=MyModule.FLAG1 | MyModule.FLAG2)
> 
> This only affects expressions not reducible at compilation time, i.e. `2+2` will appear as `4`.
> 
> 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.)
> 
> 3) `bint` appears as `bool` (instead of `int`) in autogenerated signatures, as I suggested on the mailing list.
> 
> Each change is contained in its own commit in case you want to review them separately.
>
> https://github.com/cython/cython/pull/216

I like 1) and 3), but I'm not sure about 2).

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.

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.

Stefan