On 09/23/2013 04:43 PM, R. David Murray wrote: > On Sun, 22 Sep 2013 16:19:21 -0700, Guido van Rossum <guido at python.org> wrote: >> On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel <python-dev at 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
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4