Строки документации в функциях

Соглашения о содержании и форматировании строк документации.

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

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

Синтаксический анализатор Python не удаляет отступы из многострочных строковых литералов в Python, поэтому инструменты, обрабатывающие документацию, должны при необходимости удалять отступы.

Это делается с использованием следующего соглашения:

• Первая непустая строка после первой строки определяет величину отступа для всей строки документации. Мы не можем использовать первую строку, так как она обычно смежна с открывающими кавычками строки, поэтому ее отступ не виден в строковом литерале.
• Пробел, "эквивалентный" этому отступу, затем удаляется с начала всех строк.
• Строки с меньшим отступом не должны встречаться, но если они встречаются, все их ведущие пробелы должны быть удалены.
• Эквивалентность пробела следует проверять (обычно до 8 пробелов).

Вот пример многострочной строки документации:

>>> def my_function():
...     """Do nothing, but document it.
...
...     No, really, it doesn't do anything.
...     """
...     pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.

    No, really, it doesn't do anything.