Что включать в Python Docstrings?

Question

Я хотел бы знать, что включают в себя python docstrings? Например, если я хочу документировать определенный класс, что я должен писать в docstring для этого класса?

Answer 1

По PEP 257 -- Docstring Convention:

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

Если класс подклассифицирует другой класс и его поведение в основном , унаследованное от этого класса, его docstring должно упоминать об этом, а суммировать различия. Используйте глагол «override», чтобы указать, что метод подкласса заменяет метод суперкласса и не вызывает метод суперкласса ; используйте глагол «extend», чтобы указать, что метод подкласса вызывает метод суперкласса (в дополнение к его собственному поведению).