Re: [Epydoc-devel] Epytext markup enhancement suggestions

[Edward L. <ed...@se...>]

> Epydoc is the best thing since the sliced bread happened for Python [...]

Thanks! :)

> I have been wondering if it where possible to make epytext markup even
> simpler. [...]

> 1. Leave out : (other languages don't use it either)

I'm actually fairly partial to that ": myself -- to my eyes, your
examples are hard to read because I don't know where the field body
begins.  E.g. in your proposed:

@param int|str a parameter description here

I have a strong tendency to read "a" as an indefinite article, not a
variable name.  Also, note that the "type description" doesn't have to
be a single word, or even a simple expression.  I want people to be
able to express such notions as "dictionary from int to string" or
"sequence of int" or "nonnegative int," and human language is a great
way to do it. :)  And finally, including the ":" explicitly allows us
to implement your suggestion (2) as an optional feature -- we don't
want all the docstrings people have already written suddenly and
mysteriously breaking when they upgrade epydoc!

> 2. Leave out @type, @rtype and describe type inline as the first word of
> parameter paragraph.

I wouldn't mind adding some syntax that would allow types to be
optionally specified as part of a parameter/returns field.  With your
proposal this would look like (keeping the ":" because I like it):

@param int x: the x coordinate

I also wouldn't mind any number of alternatives, including:

@param x (int): the x coordiante
@param x [int]: the x coordinate

> 3. Use | to separate different possible types

I'm not sure what you intend for the behavior to be here.  You can
already write "int|str", and it will be rendered as such in your
output.  Do you want the "|" to get translated to "or" in the output?
If not, why not just write "int or str"?

So with this modified proposal (keep ":", allow types as prefix
strings, and just use "or"), your example function would be:

def f(a, b):
    """
    @param int or str a: parameter description here
    @param module.Class b: parameter description here
    @return float: return value description here
    """"

An open question is how the "type prefix" string would interact with
epydoc's current support for having a single "@param" that describes
multiple parameters.  E.g.:

@def f(x, y):
    """
    @param x, y: The coordinates of some point.
    """

We wouldn't want "x," being interpreted as a type for y!  This would
be one advantage of a syntax like "@param x (int): ..." that more
explicitly marks the type expression.

-Edward