Writing docstrings - specifying functions arguments and returns

Question

Suppose I have a function, say:

>>> def foo(a):
        return a+1

I want to write a documentation string for it.

what is the convention in specifying in the docstring that it takes a and returns a+1?

Answer 1

The idea of a docstring is to give the user a basic overview of what's going in and coming out without telling them too much about how that happens. In this case:

def foo(a):
    """Take a number a and return its value incremented by 1."""
    return a + 1

For a less trivial example, I like the one in Dive Into Python's section on documenting functions:

def build_connection_string(params):
    """Build a connection string from a dictionary of parameters.

    Return string."""

Obviously, a more complicated function requires a bigger docstring. Just make sure the docstring is talking about what's happening (what's getting passed in, what's being returned) instead of how that's happening (implementation details should not be included).

Answer 2

PEP 257 should help!

Answer 3

For Python conventions (about this and other topics), I'd suggest first trying the Python Enhancement Proposals.

Python PEP 257 suggests for one line docstrings to specify your function like so:

def function(a, b):
"""Do X and return a list."""

but not like this:

def function(a, b):
"""function(a, b) -> list"""

because the latter example can be divined through other means.

Only glanced through them but the links from the PEP look to go to other PEP's that get into the nitty-gritty of docstrings.

As a general note I'd browse through the PEPs if you haven't yet as there are some interesting topics about Python design decisions and philosophy.

Answer 4

I personally like the style the builtins use.

>>> help(len)

len(...)

len(object) -> integer

Return the number of items of a sequence or mapping.