[Epydoc-devel] Fwd: Epytext markup enhancement suggestions

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

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

---------- Forwarded message ----------
From: Mikko Ohtamaa <mi...@re...>
Date: 15.2.2008 21:36
Subject: Re: [Epydoc-devel] Epytext markup enhancement suggestions
To: Edward Loper <ed...@se...>

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 :

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html
http://java.sun.com/j2se/javadoc/writingdoccomments/#tag
C# uses XML tags
Doxygen does not have : in Java-like mode:
http://www.stack.nl/~dimitri/doxygen/docblocks.html<http://www.stack.nl/%7Edimitri/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).

Cheers,
Mikko


-Edward
>



-