Re: [Epydoc-devel] Epytext markup enhancement suggestions

[Mikko O. <mi...@re...>]

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