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 > > 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. > -- 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.
