I had accidentally posted this to Edward when I was going to post to the list.

---------- Forwarded message ----------
From: Mikko Ohtamaa <mikko@redinnovation.com>
Date: 15.2.2008 21:36
Subject: Re: [Epydoc-devel] Epytext markup enhancement suggestions
To: Edward Loper <edloper@seas.upenn.edu>

Hi all,

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:

I have strong point to make here. This could be a taste issue. There is no official "comment document standard", but no other language uses :

C# uses XML tags
Doxygen does not have : in Java-like mode: http://www.stack.nl/~dimitri/doxygen/docblocks.html. In non-Java mode Doxygen uses \param.

I wish that we would make learning curve for people coming for other languages as low as possible. Personally, I was wondering. why epytext didn't work for my @param tags until I noticed the important :.

@param int|str a parameter description here

I have a strong tendency to read "a" as an indefinite article, not a
variable name.  

Sorry, I am not native English speaker and Finnish lacks articles :)

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

If we have formal way to define syntax, we can automatically link type definition to the correct type. Also, there is the longer description "parameter description here" for special cases. The point is to avoid extra @type definition which would lead to extra line of typing from the developer. Also, typing C{}... something around a class definition is a habit of epytext only and other document comments avoid this somehow.

Few more examples

def ban(usernames):
  @param [string] usernames  A sequence of usernames who will be banned

[] could mark dict, list and tuple. Or

def  ban(users):
    @param [mooware.models.User] A tuple of User objects

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!

I 100% agree. I don't want to break backwards compatibility. If we cannot make a parser which automatically detects these cases, I recommend that

- I can create a dialect which is a chose of the developer (__doctring__ = "epytext-java")

- A command-line switch

> 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"?

The point is that when parameter/return types are formally defined, so the parser can link it to the specific class. | is a way to define multiple return types on a single line. It really does not matter for me whether it would be | or "or". I just picked | because PHP was already using it. But after receving your feedback, it became obvious this is very non-pythonic and "or" should be used :)

This could be a usual case

def find_foo(id):
  @return Foo|None Return Foo instance or None if id is not found

istead of

def find_foo(id)
   @return: Foo instance or None if id is not found
   @rtype Foo
   @rtype None

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.

With the new syntax this could be

def f(x,y)
   @param x or y The coordinates of somepoint

Well again... I think | was useful after all, since you can concatenate all return types to a single word (no spaces) and parsing compatibility could not be achieved. It would be impossible to parse @param xory The coordines... :)

Anyways I think we are on a right track to get rid of @type and @rtype and I could help to implement some of these solutions (if not all).