Re: [Epydoc-devel] Docstring parsing shortcomings

[Hans M. <me...@in...>]

Hi!

(Resending, first try went to Edward only.)

> 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)

Let me repeat myself here: There is a use for having the name in the docs, 
namely that you can *reference* the name in the docs.  I.e. 

"""myFoo.append(obj)

This method appends obj to the end of myFoo."""

is slightly clearer than 

"""append(obj)

This method appends obj to the end of this Foo object."""

Actually, this looks like a weak argument since I chose such a simple example, 
wait a moment... look at this:

            """someFace.holeCount() -> int
            
            Returns the number of holes.  This is equal to
            len(list(someFace.holeContours())), but faster."""

OK, I could rephrase it as 

            """Returns the number of holes.  someFace.holeCount() is equal to
            len(list(someFace.holeContours())), but faster."""

if you don't want to introduce the "objName." prefix in the epydoc output, 
which I could understand because it could look a little bit inconsistent 
(however, I would only expect that in the detailed docs anyways).

> 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 was about to write that I don't understand this, but now that I wrote the 
above, I can understand you.  (This does not have anything to do with builtin 
vs. non-builtin though, does it?)

> 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.

As I said, I would prefer simply having the "L.append(object)" signature in 
the detailed HTML (not the class overview).  list.append.__doc__ is a bad 
example though, since it does not even reference 'L' in the rest of the 
docstring; I would expect sth. along
  "L.append(object) -- append object to L's end"

> >> 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 :)

Same here.. ;-)

> 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.

Actually, I remember having read that the upcoming boost 1.34.0 has such a 
feature, that is why I asked a student to try that out, but he told me that 
it hadn't.  Still, a quick search brings up this:
   http://lists.boost.org/Archives/boost/2007/04/120397.php
..which tells us that "Boost.Python now automatically appends C++ signatures 
to docstrings.".  (Note that "C++ signatures" include full C++ type specs 
before the argument names, and may not even contain the names if they were 
not specified..)

I will try that out myself now and report back.

-- 
Ciao, /  /
     /--/
    /  / ANS