Writing docstrings - defining function arguments and returning

Question

Suppose I have a function, for example:

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

I want to write a documentation line for it.

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

Answer 1

The idea behind docstring is to give the user a general overview of what happens and goes out, without saying too much about how this 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 found in Dive Into Python for documenting functions:

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

    Return string."""

, -. , docstring , ( , ) , ( ).

Answer 2

Python ( ), Python Enhancement .

Python PEP 257 docstrings :

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

:

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

.

, PEP , PEP, nitty-gritty docstrings.

, PEP, , Python.

Answer 3

PEP 257 !

Answer 4

, .

→> help (LEN)

LEN (...)

len(object) -> integer

Return the number of items of a sequence or mapping.