[SciPy-dev] Docstring standards for NumPy and SciPy

[Travis Oliphant]

>
> I've been using
>
> Required Arguments
>      arg1 -- blah, blah
>
> Keyword Arguments
>     kw1 -- blah, blah
>
> Return
>     ret -- blah
>
>
> Not all arguments are inputs, some are for outputs, so the word input 
> is a bit confusing. I note that Robert has been using word parameters 
> instead without distinquishing keyword arguments. Anyway, if we are 
> going to have a separate entry for keyword arguments, I would rather 
> put it right after the required arguments. I've also been single 
> quoting variable names in the text but am not happy about that. Should 
> we have someway to mark variable names?


True, not all arguments are for inputs.  So, put them in the output 
section.  That's why they are called inputs and outputs.  It's also why 
I want to label the outputs section with the name you are giving to what 
actually is returned by the function (rather than through a keyword 
argument which would be in the output section but labeled differently). 
If the function returns a tuple, then this should be noted using a 
comma-separated list of names that are then explained.

I personally dislike marking variable names and don't like to read 
documentation with variable names that are cluttered with marks.  That's 
one of the things that bothers me the most about reST.