Re: [Epydoc-devel] Docstring parsing shortcomings

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

Hi again!

Am Donnerstag, 10. Mai 2007 20:57:17 schrieben Sie:
> 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.

That is interesting, I did not know that it was discouraged, but that makes 
sense indeed.

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

I agree.  While I wrote the above, the idea looked less and less like a good 
one to me. ;-)  However, I now changed this docstring for example:

    """simplifyMapEdges(map, perpendicularDistEpsilon)
    simplifyMapEdges(map, perpendicularDistEpsilon, maxStep)

    Changes ..."""

like this to mark the last argument as optional:

    """simplifyMapEdges(map, perpendicularDistEpsilon[, maxStep])
    ..."""

epydoc recognizes this (cool!), but displays it with an ellipsis:

   simplifyMapEdges(map, perpendicularDistEpsilon, maxStep=...)

This is not really what I want; can epydoc be modified to display the optional 
argument in square brackets like in the docstring?

In case this is relevant, the Python definition is:

def simplifyMapEdges(map, *args):
    """simplifyMapEdges(map, perpendicularDistEpsilon[, maxStep])

    Simplifies all edges in-place ..."""
    pass

Ciao, /  /
     /--/
    /  / ANS