[Epydoc-devel] Docstring parsing shortcomings

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

Hi!

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.

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.

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

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

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

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