Hello all,

Epydoc expects to find a *single* description of the type of a
parameter.  I.e., the correct way to write that is:

    @param x: blah
    @type x: None or str

Ah,  my bad then =)


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


Some markup languages that use ":" as a field separator:
  - rfc822-style headers (very widely used, eg by email)
  - restructuredtext

That's true. The point I was trying highlight is that other programming languages and comment documentation systems do @param without :. I want to make it easy for people migrating from other languages - Python is catching more and more fire every day (the programming language of 2007 and so on). When I started to document my code with Epytext, which is the easiest documentation tool available for Python currently, I found this : issue very frustrating, since my previous habits tend to make me type @param without :.

@group Group Name: x, y, z
@var x, y, z: Description of several variables at once
@param x, y, z: Description of several parameters at once

These would not be possible if there was no colon.

True. I am not suggesting ditching @xxx y: syntax completely. I just hope it could be left out from the simplest cases which I belive 80% of documentation lines are. The ultimate goal is to streamline the grunt work and have big cannons available for hard cases =)

Epytext already detects the case where you have a line that starts
with "@" but there's no corresponding ":" -- and it flags it as a
warning.  

Trust me, I have seen a lot of these warnings =)
 
So I guess I might be ok with making the ":" optional.  That way,
things like "@group Group Name: x, y, z" would continue to work, but
things like "@param x description" would also work.  The following
case might trip people up sometimes:

    @param x this is a description of x.  Read about: y

where there's a ":" further along in the first line (after "Read
about").  But I guess that would be fairly rare, and epydoc should be
able to complain in that case.  

You are righ. This would also fall into "special cases" which probably don't appear that often.
 

So, given all that, my counterproposal
is for epytext to understand the following syntaxes:

 

@param x: This is a description of x.
@param x This is a description of x.
@param x (int) This is a description of x.
@param x, y, z: A description of three variables
@group Name of Group: x, y, z
@group Transformers x, y, z
@return int: This is a description of the return value.
@return This is a description of the return value.
@return: This is a description of the return value.

Here is another suggestion which we might have not discussed before.

@param x (int): This is a description of x.

-->

@param int x: This is a description of  x
@param MyClass x: This is a description of x
@param int or string x: This is a description of x
@return int x: This is a description of type


Parameter type rule: If there are several words before the colon of @param line, threat the last word as a parameter name and the former words as a type description. This resembles more C-like syntax which is widely recognized and I believe Javascript (Ext JS) does this. In PHP documentation, another languague having dynamic types, the syntax would be:

@param int $x This is a description of x. Since Python doesn't (luckily) have $ notitation, $ wouldn't fit well.


So the ":" is required for:
  - @return with type
  - @param w/ multiple vars

Right. But let's consider above "type definition" notation for @return and @param. 

And optional in all other case.  

Backwards compability++ :)
 
I don't like having types be prefixed -- it makes
it too hard to scan for the name of the param,

Consider above type definition example with colon. I find it quite readable, since parameter name is always left from the colon. Some perfectionist could add some whitespaces to align all parameter names into a column.

which is much more
important than the type.  More important information should come
before less important information.)  Return types are specified as an
argument to the field.

I agree. However, due to all statically typed languages out there, people have used to have int before their x.
 

Of course, there are some issues with this proposal, and the way
markup languages are currently set up.  One is that there is currently
a very strong abstraction barrier between epytext and epydoc --
epytext defines a markup syntax for field lists, but has nothing to
say about what fields can be used, or what their meanings are.  In
order to allow some fields (like @param) to automatically eat the
first following word as an argument, while others (like @summary)
don't, will require that abstraction barrier to be weakened -- epytext
will need to know what fields are expected, and what to do with them.

I haven't yet checked how epytext and epydoc play together - I have only experience hacking Doxygen. I believe the problem could be solved by adding "postprocess" step when the documentation is compiled: all type information is out there to exploit. It could go through @param definitions and do the magic - users love magic as an alternative for hand-typing!
 
So what do you think of this proposal?

I think it's heading to the right way when pursuing my goal of having better compatibility with other documentation languages.

p.s., on the topic of creating a formal language for expressing types:
unless Python defines a standard formal language for types, I'm
strongly opposed to coming up with our own.  "Explicit is better than
implicit" is the second rule in the zen of python. :)  Your suggested
format:

    @param [int] x description...

Makes me think x is an integer, not a list of ints.  Also, note that
Python is a language with a strong culture of duck typing, and precise
notions of type are often not applicable.

A very good point. How about

@param list x: The description of x.

Since Python lists (tuples, dicts) are generic types, the documentation does not "want to tell" what's inside the list.

..or...

@param list(int) x: The description of x

and

@param dict(str, MyClass) x: The description of x
@param tuple(int) x: The description of x

These resemble the Python syntax somehow. Collection-like return types are an issue which could be discussed through too!


--
Mikko Ohtamaa
www.redinnovation.com
Every problem is solvable if you can throw enough energy drinks at it