On 09/23/2013 04:43 PM, R. David Murray wrote:
On Sun, 22 Sep 2013 16:19:21 -0700, Guido van Rossum <gu...@python.org> wrote:
On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel <python-...@masklinn.net>wrote:
The points here are that there's a single source of truth (so we can't
have conflicting docstring and rst documentation), and documentation
becoming outdated can be noticed from both docstring and published
documentation.
Another thing that hasn't been mentioned about docstrings vs rst docs,
is that even when the text is identical, it generally isn't. By that I
mean the rst docs have ReST markup, but the docstrings don't. So using
FYI, the scientific Python community have their own standard (the NumPy
docstring standard), with light RST markup in docstrings:
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
It's a fairly popular standard in the scientific sub-culture.
I think there's something about scientific codes which tips the scales
away from Guido's position of short docstrings being better; when
working with computation, you pretty much need the documentation,
formulas, references to paper it is based on and so on in order to read
and understand the code in the first place, so interspersing makes more
sense than it may in the stdlib. Seeing code with references "x",
"alpha", "beta", "gamma" without their definition is pretty useless :-)
Dag Sverre
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
