Написание строк документации - указание функций аргументов и возвратов

Question

Предположим, у меня есть функция, скажем:

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

Я хочу написать строку документации для него.

Каково соглашение при указании в строке документации, что он принимает и возвращает +1?

Answer 1

Идея документирования заключается в том, чтобы дать пользователю базовый обзор того, что происходит и выходит, не рассказывая им слишком много о том, как это происходит. В этом случае:

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

Для менее тривиального примера мне нравится пример в разделе Dive Into Python о документировании функций:

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

    Return string."""

Очевидно, что более сложная функция требует большей строки документации. Просто убедитесь, что строка документации говорит о том, что происходит (что передается, что возвращается), а не о том, как это происходит (подробности реализации не должны быть включены).

Answer 2

PEP 257 должен помочь!

Answer 3

Для соглашений Python (об этой и других темах) я бы предложил сначала попробовать предложения по улучшению Python.

Python PEP 257 предлагает для одной строки документации указать вашу функцию следующим образом:

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

но не так:

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

потому что последний пример может быть предсказан другими способами.

Только пролистал их, но ссылки из PEP смотрят на другие PEP, которые попадают в тончайшие строки документации.

В качестве общего примечания я бы пролистал PEP, если у вас еще нет, поскольку есть некоторые интересные темы о решениях и философии Python.

Answer 4

Мне лично нравится стиль, который используют встроенные.

>>> помощь (лен)

Len(...)

len(object) -> integer

Return the number of items of a sequence or mapping.