I had accidentally posted this to Edward when I was going to post to the list.
---------- Forwarded message ----------
From: Mikko Ohtamaa <email@example.com>
Date: 15.2.2008 21:36
Subject: Re: [Epydoc-devel] Epytext markup enhancement suggestions
To: Edward Loper <firstname.lastname@example.org>
Thank you for great feedback. It's nice to see discussion which could lead to the evolution of open source tools :)
> 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
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!
> 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.