epydoc-devel

[Epydoc-devel] Convention for referencing params in function documentation

[Joseph T. <tu...@gm...>]

What is the appropriate convention for referencing params in function
documentation?
e.g.

def max(x):
   """
   @return: The largest element of I{x}.
   """

(Obviously, I could make @param x:, but this is just for the sake of
explanation.)

Is there a convention for annotation params in the function documentation?
I could italicize them all, but this is brittle and one may want to change
the formatting later on.

Thanks,
   Joseph

-- 
Academic: http://www-etud.iro.umontreal.ca/~turian/
Business: http://www.metaoptimize.com/

Re: [Epydoc-devel] Convention for referencing params in function documentation

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

On Thu, Apr 17, 2008 at 1:31 PM, Joseph Turian <tu...@gm...> wrote:
> What is the appropriate convention for referencing params in function
> documentation?
> e.g.
>
> def max(x):
>    """
>    @return: The largest element of I{x}.
>    """

In epytext, I usually just use C{x} for function parameters.  In
restructured text, I usually use `x`.  Both conventions have the
disadvantage you mention -- that it would be nontrivial to change
formatting later on.  But I've never found myself wanting to change
the formatting, and don't expect to in the future.  I don't think the
potential of maybe wanting to change formatting in the future is worth
the overhead of adding new markup syntax (in terms of human memory
space and markup learning curve).

(For some projects, I would just write x -- i.e., no markup. :)

-Edward