On Sun, Sep 22, 2013 at 8:49 AM, Barry Warsaw <barry at python.org> wrote: > On Sep 22, 2013, at 10:34 AM, Brett Cannon wrote: > > >The rule of thumb I go by is the docstring should be enough to answer the > >question "what args does this thing take and what does it do in general to > >know it's the function I want and another one in the same module?" quickly > >and succinctly; i.e. just enough so that help() reminds you about details > >for a module you are already familiar with that might come up while at the > >interpreter prompt. Everything else -- in-depth discussion of the > >algorithms, extra examples, why you want to use this function, etc. -- all > >go in the .rst docs. > > That's exactly my own rule of thumb too, so +1. > It makes a lot of sense to me too. That said, I don't see a reason why we can't auto-generate the referenc-y stuff from docstrings into the .rst automatically, i.e.: module.rst: Algorithms, bla bla bla, examples bla bla bla <ref:module.py Foo.bar> # << Auto generator pastes function signature and docstring here More algorithms, more bla bla, examples. Eli -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20130922/05930883/attachment.html>
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