[Cython] autodoc function/method signatures

[Robert Bradshaw]

On Sep 8, 2008, at 9:39 AM, Lisandro Dalcin wrote:

> On Mon, Sep 8, 2008 at 1:18 PM, Robert Bradshaw
> <robertwb at math.washington.edu> wrote:
>> On Sep 8, 2008, at 7:41 AM, Lisandro Dalcin wrote:
>>
>> Yes, it certainly is! One thing that worries me is that adding a
>> bunch of tree traversals starts to slow things down--at the very
>> least we should have a transform that doesn't descend into function
>> bodies for speed reasons for stuff like this.
>
> Well, I believe my current code do not descend into functions body,
> but perhaps I'm wrong.

Good. It's just that the default does descend all the way down.

>>> Now I would like to know your opinions about
>>> how the signatures should be rendered. Robert, if you see this,  
>>> please
>>> enter the discussion.
>>
>> I'd render them the natural way, e.g. [return-type] name([type] arg,
>> [type] arg, ...)
>>
>
> That's the natural way from a C function. Docstrings do not apply for
> 'cdef' functions, but for 'cdef' of 'cpdef'.
>
> Additionally, for 'def' functions, I have no idea how to provide a
> good 'return-type'.

Not sure I'm understanding your question... for def functions the  
return type is always object, which is implied (i.e. one doesn't have  
to explicitly write "object").

> We should handle default aguments; I'm currently using
> 'arg.default.compile_time_value(None)' (I'm passing 'None' to the call
> because not sure at this point what to pass).  If this fails, I just
> use '<???>'.

That sounds like a good first pass to me. I think a context object  
goes here, right?

> Other stuff I'm not sure how to render is __get__/__set__/__del__ on
> properties. Should I generate docstrings for them?

Maybe, though those are lower priorities.

- Robert