Re: [Epydoc-devel] Docstring parsing shortcomings

[Edward L. <ed...@gr...>]

On May 10, 2007, at 2:57 PM, Daniele Varrazzo wrote:
> Edward, what is the rationale behind the "selfparam" in the function
> signature parsing? It seems to me that dropping it would produce  
> better
> results in most cases (even for a bound method expressed whose  
> signature in
> the docstring is expressed as
>
>    inst.func(a, b)
>
> reporting "func(a, b)" seems kinda more correct than "func(inst, a,  
> b)",
> even if the self argument is missing)

I took the lead here from the python builtins:

     >>> print list.append.__doc__
     L.append(object) -- append object to end

It made most sense to me to render the docs for this as "append(L,  
object)" to be consistent with how non-builtin object methods are  
represented.  I'm not strongly attached to the decision, though, if  
there's support for changing this.  But I'd like the generated docs  
for the builtin objects to still make sense.

>> d) It would be great it epydoc could extract signatures for  
>> boost::python
>> exported functions, too [...]
>
> I don't know much about boost::python bindings. Shooting random  
> parameters
> to an unknown signature doesn't seem fair to me :) sip generated  
> bindings
> share a similar characteristic (actually sip doesn't generate any  
> docstring
> at all, i don't know about boost). If you point me at an OS project  
> built
> with boost i may play a bit with such functions.

Perhaps boost and/or sip could be encouraged to include some  
introspectable value that can be used to find the signature?  Either  
by automatically including a signature at the beginning of the  
__doc__ attribute, or by adding a new attribute to the object?  If  
they did that, I'd be happy to add support to epydoc for reading it.

-Edward