Re: [Epydoc-devel] Docstring parsing shortcomings

[Daniele V. <pi...@de...>]

Hello Hans,

> Today, I tried epydoc (3.0beta1) on one of my projects, and found several
> things that I miss / find strange:
>
> a) When parsing a signature that is in the first line of a function's
> docstring, epydoc fails to recognize signatures with default arguments (cf.
> test5 in the attached test file).  I later noticed that I could strip them
> from the docstrings since epydoc will extract the default values from the
> function signature nevertheless, but I still see this as a shortcoming.

there was a bug indeed in the signature parsing: the regexpr used was fooled
by the spaces around the '=' symbol (actually by the one before: the one after
was correctly recognized). This wasn't widely tested because the function
signature is conventionally expressed without spaces around the '=' symbol -
see PEP 8; nevertheless i have enforced the signature parsing in the trunk
rev1589.

Also notice that the PEP 275 discourages to duplicate the function signature
in the docstring for pure Python modules: it can be retrieved by
introspection.

> b) When documenting a method, I like to write an object name in front of the
> signature in order to be able to reference the object by name in the
> documentation.  E.g. "someFoo.testMeth2(a, b)" in the attached file.
> Interestingly, epydoc *does* parse the object name, but it does not display
> it properly but introduce a new parameter of that name.  That looks like a
> bug to me, even if you could argue that it is the name of the object passed
> as "self" / first argument.  However, IMO the signature documents the
> *usage*
> of a function and there you would not call "Foo.testMeth2(someFoo, a, b)"
> but
> someFoo.testMeth2(a, b).  Comparing the documentations of testMeth1 and
> testMeth2 is also irritating, since both take the same number of arguments,
> but it looks different.

This is something the author has deliberately decided to do. Anyway it bit
me too once: this "feature" also kicks in when documenting a module
function. IIRC the psycopg signature for the "connect()" function was
expressed as "psycopg.connect()" and it appeared as "connect(psycopg)". I
was maintaining psycopg documentation, not epydoc yet, so i preferred to
change the function signature.

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)

> c) (enhancement proposal) Finally, I would like to be able to specify
> several
> signatures for the same function.  Sometimes, it is possible to call a
> function with different types of objects / different keyword arguments /
> ...,
> and I would like to document two different kinds of use cases.  (Yes, this
> is
> a little bit like function overloading, not really pythonic and not very
> important to me either.)

mmm... this is definitely to be documented in the docstring body. Python
doesn't support methods overloading: i don't think Epydoc should document a
function "as it were implemented in C++".

> d) It would be great it epydoc could extract signatures for boost::python
> exported functions, too (I am using boost 1.33.1 here, but I was told that
> 1.34.0 makes no difference here). Alas, I don't know how that is possible -
> the only way I know of displaying the signature / getting the info is to
> actually *call* the functions (argh!) with a dummy argument and parse the
> resulting error message. :-(  One can define a dummy class and rely on the
> fact that no function will ever do something with e.g. 42 arguments of that
> type, but that procedure looks really brittle to me, although we use that
> for
> tab-completion in an interactive python shell (but there, only single
> functions are called on demand, so this is less dangerous).

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.

> Otherwise, epydoc really looks impressive to me (rst support, nice
> output, ...)! :-)

Thank you ;)

Ciao ciao

-- 
Daniele Varrazzo - Develer S.r.l.
http://www.develer.com