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