[Epydoc-devel] Epytext markup enhancement suggestions

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

Hi all,

Epydoc is the best thing since the sliced bread happened for Python which
otherwise lacks naming conventions and such. The goal of documentation is to
make the process simple as possible, so that it wouldn't "hinder" the work
of development and that's what Epydoc does well.

I have been wondering if it where possible to make epytext markup even
simpler. Based on my experiences in PHP and Java formal comment blocks, here
are some suggestions:

def f(a, b):
    """
    @param int|str a parameter description here
    @param module.Class b parameter description here
    @return c float return value description here
    """"

Versus (old style)

def f(a, b):
   """
   @param a: parameter description here
   @type a: int
   @type a: str
   @param b: parameter description here
   @type b: module.Class
   @return:  return value  description here
   @rtype: float
   """

I see a consirably win =)

1. Leave out : (other languages don't use it either)

2. Leave out @type, @rtype and describe type inline as the first word of
parameter paragraph.

3. Use | to separate different possible types

These changes can be made compatible with existing Epytext markup with some
smart logic (i.e. new syntax if effective if : is left out).

Now, tell my why this wouldn't be possible or I start to submit patches :)

-- 
Mikko Ohtamaa
Red Innovation Ltd.
+358 40 743 9707
www.redinnovation.com
Every problem is solvable if you can throw enough energy drinks at it