[Python-Dev] Best practice for documentation for std lib

[Barry Warsaw]

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.

-Barry