Re: [Epydoc-devel] Docstring parsing shortcomings

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

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

Hello,

you should consider that not everybody has the same conventions to write the
signature. While a certain quantity of heuristics can be applied, i am sure
there will always be a funky example baffling the parser, unless a precise
grammar is specified.

The situation is worse if the signature description is actually different
from what can be introspected: in your latter example a function accepting a
list of positional argument is disguised behind a signature taking two
_named_ parameters, the second of which optional.

A more pythonic way to write your function would be, in my opinion::

    def simplifyMapEdges(map, perpendicularDistEpsilon, maxStep=None):
        """Simplifies all edges in-place.

        :Parameters:
          - `map`: the object to modify
          - `perpendicularDistEpsilon`: you know what it is.
          - `maxStep`: max number of steps. If omitted will be guessed.
        """

There is both a docstring conventions issue and a "pythonic" way to write a
function signature. You may have a good implementation reason to say "*arg"
instead of what i propose: if so, there's noting to be told. But i'd be more
"sincere" in this case and avoid the description of names which are in fact
not used: instead i'd describe in the docstring what the function really
takes as its input and how the caller should invoke. Or else somebody could
try to call your function as "simplifyMapEdges(mymap,
perpendicularDistEpsilon=42)", that will raise an exception.

If forced to keep your signature, i'd write a docstring such::

    def simplifyMapEdges(map, *args):
        """Simplifies all edges in-place.

        :Parameters:
          - `map`: the object to be updated
          - `args`: further positional arguments. At least the first is
            mandatory:

            1. the Perpendicular Distance Epsilon
            2. the max number of steps. If omitted will be guessed.

            Furhter parameters are ignored.
        """

I know that "pythonic conventions" are not the only ones existing, but they
are the most probable in a Python project, so Epydoc is tweaked to do its
best if they are applied and do something in between "what it can" and
"tries to survive" in all the other ones :)

I think you will obtain the best results avoiding to repeat yourself (adding
a signature where it can be introspected instead) and adding descriptions
really matching the "real situation" (which is also useful to detect
errors).

About a point you have raised somewhere else: when a docstring is more than
a paragraph long, only the first is printed in the summary table, while the
complete docstring content is put in a box below. You may found this, and
other useful hints, in the fine manual (tm) ;)

Regards :)

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