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

Question

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

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

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

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

Answer 1

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

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

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

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

    Return string."""

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

Answer 2

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

Answer 3

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

Python Pep 257 предлагает одну строку Docstrings указать вашу функцию так:

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

но не так:

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

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

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

Как общая записка, я бы просматривал PEPS, если вы еще этого не сделали, так как есть несколько интересных тем о дизайнерских решениях Python и философии.

Answer 4

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

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

Лен (...)

len(object) -> integer

Return the number of items of a sequence or mapping.