04.01.2012 03:19, Aaron Meurer пишет:
> On Tue, Jan 3, 2012 at 1:10 PM, miham <[email protected]> wrote:
>> Lately there has been some efforts to standardize docstrings in SymPy.
>> The effort has been pretty successful (more info: [1]), but some
>> questions remain open, so I thought it might be worth asking what the
>> community thinks. Here are the questions:
>>
>> 1. Should the summary be on the same line as the opening quotes ("""),
>> or on the next line?
>
> I don't like this, but I don't think we should require either way
> (docstrings should be consistant within the same module, but that's
> it). Personally, the off center just makes things look bad, and
> anyway, you lose three characters for your "one-line" summary if you
> do this.
>
> vim is pretty extensible, and I've found the extension language to be
> very easy to use. It's probably possible to extend the folding to
> always show the first line with some plugin or maybe even a few lines
> in your .vimrc.
>
>> 2. Should there be a blank line after every section header?
>
> I agree. This greatly improves readability.
>
>> 3. Should the order of sections be predefined or left to the
>> discretion of the developers.
>
> I don't care about this. We already apparently have to require that
> only specific words be header for the numpy doc extension to work
> (though I think this can be fixed).
>
> I would try to stray away from having too many fixed requirement for
> the formatting of docstrings, as I think it's better to leave it up to
> the writer to use his best judgement for what he wants to say. Also,
> not all docstrings are equal because not all functions are equal. For
> example, some docstrings just document what the function/class is
> (most things in the functions module are like this). Others have a
> some kind of discussion about various things (see e.g., the simplify()
> docstring). Of course, we should require that each docstring be
> formatted in a way that works well with Sphinx.
>
> Aaron Meurer
>
Regarding the order.
Taking into account that this question is raised in pull request 938,
taking into acount that the section order of SciPy/NumPy [2] is not a
single etalone, (e.g. Sage's section order has 'Examples' upper, and
'References' below.)
And that I totally agreed with Aaron's arguments, I vote to have *not* a
strict section order. Only as recommendation or as an example.
P.S.
And about the example of order, now in [1] it is like
Short summary
Deprecation warning
Extended summary
Parameters
Returns
Other parameters
Raises
See Also
Notes
References
Examples
For myself only, I tend to put "Examples" upper, and "References" below.
And "See Also" after the examples. I try to explain it, that I split it
in my mind as:
# Text description
Short summary
Deprecation warning
Extended summary
# Technical information
Parameters
Returns
Other parameters
Raises
# Use cases: look here, to see, try it or to see the other things.
Examples
See Also
# Additional text info.
# Read it after the above things are read, so it is clear
# what are the notes about.
# And only if you interested in it.
Notes
# Go away to the library only,
# when the above text is not sufficient.
References
[1] https://github.com/sympy/sympy/wiki/Writing-documentation
[2] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
[3] http://vim.wikia.com/wiki/Folding
[4]
http://www.sagemath.org/doc/developer/conventions.html#docstring-markup-with-rest-and-sphinx
>>
>> Here are my preferences:
>>
>> 1. I would put the summary on the same line as the opening quotes. I
>> use vim folding [3], so when i open a python file, i see only function/
>> class definitions and the first line of docstrings (because they are
>> the first line of the new indentation level). Thus i can get quick
>> overview of a file.
>> 2. I would put a blank line after every section header, because it
>> makes it more readable.
>> 3. I think that predefined section order is a good thing, because the
>> consistency makes information easier to find (you know where to look
>> for it). SciPy/NumPy section order [2] could be used.
>>
>> Luckily none of these conventions would make developer's work any
>> harder. Quite the contrary - it is easier to do the right thing if you
>> know what the right thing is.
>>
>> [1] https://github.com/sympy/sympy/wiki/Writing-documentation
>> [2] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
>> [3] http://vim.wikia.com/wiki/Folding
>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "sympy" group.
>> To post to this group, send email to [email protected].
>> To unsubscribe from this group, send email to
>> [email protected].
>> For more options, visit this group at
>> http://groups.google.com/group/sympy?hl=en.
>>
>
--
Alexey U.
--
You received this message because you are subscribed to the Google Groups
"sympy" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sympy?hl=en.
