Ruff undocumented-public-function (D103)
undocumented-public-function проверяет отсутствие документации для публичных функций.
Почему это неправильно
Публичные функции должны быть документированы с помощью docstring, который описывает их назначение и поведение. Обычно docstring функции должен:
- Описывать поведение функции.
- Перечислять её аргументы.
- Описывать побочные эффекты.
- Указывать возможные исключения.
- Описывать возвращаемые значения.
- Содержать любую другую информацию, важную для пользователя.
Если кодовая база придерживается определённого стандарта оформления docstring для функций (например, NumPy или Google), следуйте ему для единообразия.
Пример ошибки
def calculate_speed(distance: float, time: float) -> float:
try:
return distance / time
except ZeroDivisionError as exc:
raise FasterThanLightError from exc
Как правильно
В формате NumPy:
def calculate_speed(distance: float, time: float) -> float:
"""Calculate speed as distance divided by time.
Parameters
----------
distance : float
Distance traveled.
time : float
Time spent traveling.
Returns
-------
float
Speed as distance divided by time.
Raises
------
FasterThanLightError
If speed is greater than the speed of light.
"""
try:
return distance / time
except ZeroDivisionError as exc:
raise FasterThanLightError from exc
Или в формате Google:
def calculate_speed(distance: float, time: float) -> float:
"""Calculate speed as distance divided by time.
Args:
distance: Distance traveled.
time: Time spent traveling.
Returns:
Speed as distance divided by time.
Raises:
FasterThanLightError: If speed is greater than the speed of light.
"""
try:
return distance / time
except ZeroDivisionError as exc:
raise FasterThanLightError from exc
