Аннотация

Данный PEP документирует семантику и соглашения, связанные с использованием Python docstrings [прим. Мне не очень нравится использовать термин «документация», потому что в моём понимании он имеет более общее значение, поэтому я буду придерживать названия «документационные строки» ].

Обоснование

Цель данного PEP заключается в стандартизации высокоуровневой структуры документационных строк: описать, что именно они должны содержать и объяснять (При этом мы не будем обговаривать фактический синтаксис [примеч. имеется ввиду, что ответственность за формализм переходит к Epytext, reST и т.д.] ). PEP содержит соглашения, а не законы или конкретный синтаксис.

«Универсальное соглашение обеспечивает ясность, логичность, удобство сопровождения и основу для хороших навыков программирования. Но оно не заставляет вас действовать против своей воли. Это Python!»

Тим Питерс на comp.lang.python, 2001-06-16

Если вы избегаете соглашений, в худшем случае на вас посмотрят немного не взрачно. Но есть некоторых приложения (Например такие, как система документирования Docutils), которые позволят вам добиться более качественного результата, если вы будете осведомлены о принятых конвенциях и следовать им.

Спецификация

Что такое Docstring?

Документационная строка — это строковый литерал, который встречается как первая инструкция в определении модуля, функции, класса или метода. Такая строка становится доступна при обращении с специальному атрибуту __doc__ этого объекта.