[SciPy-user] SciPy-user Digest, Vol 41, Issue 18

Janet Swisher swisher at enthought.com
Wed Jan 10 15:28:57 CST 2007


Robert Kern <robert.kern at gmail.com> wrote:

> This is the Enthought standard:
>
>
> Parameters
> ----------
> var1 : type of var1 (loosely)
>     Description of var1.
> variable2 : type of variable2 (loosely)
>     Description of variable2.
> kwdarg : type of kwdarg, optional
>     Description of kwdarg.

> One issue that should be noted is that sometimes the description
> of a variable is omitted because the description of the function, the variable
> name, and the type information are more than enough context to tell you
> everything you need to know about the parameter. The only description you can
> give is just a repetition of the information that you just gave. Or two
> variables are substantially similar such that you want to describe them together
> only once.
>
> """ Clip the values of an array.
>
> Parameters
> ----------
> arr : array
> lower : number
> upper : number
>     The lower and upper bounds to clip the array against.
> """
>
> This is one reason why I'm beginning to like the ReST form of this; it always
> has a marker to say that this is part of a list.

The first form above *is* a ReST list -- a definition list. However, 
ReST definition lists *require* a description paragraph for each item.

> """ Clip the values of an array.
>
> :Parameters:
>   - arr : array
>   - lower : number
>   - upper : number
>     The lower and upper bounds to clip the array against.
> """

I think ReST would interpret this as a bullet list. However, as written, 
it would output the description on the same line as the last bullet. To 
make the description come out as a continuation paragraph, it would need 
a blank line in between, which arguably creates too much visual 
separation in the source, especially if there are more items:

:Parameters:
  - arr : array
  - lower : number
  - upper : number

    The lower and upper bounds to clip the array against.

  - another : number

-- 
Janet Swisher --- Senior Technical Writer
Enthought, Inc. http://www.enthought.com



More information about the SciPy-user mailing list