[Python-Dev] Best practice for documentation for std lib (original) (raw)

Walter Dörwald walter at livinglogic.de
Mon Sep 23 13:27:47 CEST 2013

On 22.09.13 16:34, 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.

It would be great if the docstring contained a link to the online documentation.

Servus, Walter

More information about the Python-Dev mailing list