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
> > 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
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
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
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
> @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.
@param list(int) x: The description of x
@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!
Every problem is solvable if you can throw enough energy drinks at it