[Cython] autodoc function/method signatures

[Stefan Behnel]

Hi,

Lisandro Dalcin wrote:
> On Mon, Sep 8, 2008 at 5:17 PM, Stefan Behnel <stefan_ml at behnel.de> wrote:
>> I don't think there's much gained by additionally providing type information,
>> for example.
> 
> But what about IPython? Type information is valuable when typing, for example
> 
> In [1]: from petsc4py import PETSc
> In [2]: PETSc.Mat.mult?
> Type:           method_descriptor
> Base Class:     <type 'method_descriptor'>
> String Form:    <method 'mult' of 'petsc4py.PETSc.Mat' objects>
> Namespace:      Interactive
> Docstring:
>     mult(self, Vec x, Vec y)

Ok, I agree that that's helpful. Just go for it.


>>> Other stuff I'm not sure how to render is __get__/__set__/__del__ on
>>> properties. Should I generate docstrings for them?
>> There's only one visible docstring for them, which is the docstring of the
>> property itself (i.e. of the descriptor). So augmenting the docstring doesn't
>> make much sense.
> 
> OK, so getting this (at least inside IPython) is just fine, right?
> 
> In [3]: PETSc.Vec.size
> Out[3]: <attribute 'size' of 'petsc4py.PETSc.Vec' objects>
> 
> In [4]: PETSc.Mat.size
> Out[4]: <attribute 'size' of 'petsc4py.PETSc.Mat' objects>

Yes, that's just fine. Being a property or not is just an implementation
detail. In extension classes, attributes tend to be properties much more often
than in Python code, but users don't need to see that.

Stefan