Re: [Epydoc-devel] Epytext markup enhancement suggestions

[Edward L. <ed...@se...>]

> Here is another suggestion which we might have not discussed before.
>
> @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

The "@return" example doesn't make sense to me -- there's no variable
name associated with a return value.

For the "@param" examples -- I understand that this ordering has a
long history, and is very familiar from statically typed languages.
Nevertheless, I still find myself reluctant to add it.  Let's add the
postfix parenthesized form (i.e., "@param x (int): descr", try it out
for a while, and then you can tell me if you think this prefix form is
still necessary.  To quote the Zen of Python again, "There should be
one -- and preferably only one -- obvious way to do it."

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

I can see how the difference between having a colon and not could trip
people up -- the circumstances of using @param in other languages and
@param in epydoc is very similar.  But this (prefixed types) is more a
case of something that might be familiar to users, not something that
might trip them up.

> > on the topic of creating a formal language for expressing types: [...]
>
> A very good point. How about
>
> @param list x: The description of x.
> @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

You're free to use this homegrown type specification language yourself
-- epydoc will render them just as you type them, and it will be up to
your documentation readers to interpret them.  But I don't want to
make it (or any other non-standard type specification language) part
of epydoc itself.  So, as I said before, unless Python adopts a
standard type specification language (which seems unlikely to me),
epydoc won't support one.

-Edward