Ruff undocumented-public-module (D100)
undocumented-public-module проверяет отсутствие документации для публичных модулей.
Почему это неправильно
Публичные модули должны содержать docstring, который описывает их назначение и содержимое. Обычно docstring модуля должен:
- Кратко описывать цель модуля.
- Перечислять экспортируемые классы, исключения, функции и другие объекты с однострочным резюме каждого.
Если модуль используется как скрипт, его docstring должен служить сообщением об использовании (usage). Если в проекте принят определённый стиль оформления модульных docstring (например, по PEP257), следуйте ему для единообразия.
Пример ошибки
class FasterThanLightError(ZeroDivisionError): ...
def calculate_speed(distance: float, time: float) -> float: ...
Как правильно
"""Утилитарные функции и классы для вычисления скорости.
В этом модуле:
- FasterThanLightError: исключение при вычислении сверхсветовой скорости;
- calculate_speed: вычисляет скорость по расстоянию и времени.
"""
class FasterThanLightError(ZeroDivisionError): ...
def calculate_speed(distance: float, time: float) -> float: ...
