Как использовать строки документации в модулях Python?

Строки документации (docstrings) в Python пишутся сразу после определения функции, метода, класса или модуля. 2 Они используются для документирования кода. 2

Для модулей строки документации помещаются в начало файла, перед любым импортом. 1 Они должны включать: 1

• краткое описание модуля и его назначение; 1
• список любых классов, исключений, функций и любых других объектов, экспортируемых модулем. 1

Для функций модуля строки документации должны содержать: 1

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

Строки документации могут иметь различное форматирование. 4 Для более удобной работы с документацией в Python существует встроенная библиотека pydoc, которая автоматически генерирует документацию из модулей. 4

Соглашения о строках документации описаны в PEP 257. 1