Ruff undocumented-public-method (D102)
undocumented-public-method проверяет отсутствие документации для публичных методов.
Почему это неправильно
Публичные методы должны быть документированы с помощью docstring, который описывает их назначение и поведение. Обычно docstring метода должен:
- Описывать поведение метода.
- Перечислять его аргументы.
- Описывать побочные эффекты.
- Указывать возможные исключения.
- Описывать возвращаемые значения.
- Содержать любую другую информацию, важную для пользователя.
Если кодовая база придерживается определённого стандарта оформления docstring для методов (например, NumPy или Google), следуйте ему для единообразия.
Пример ошибки
class Cat(Animal):
def greet(self, happy: bool = True):
if happy:
print("Meow!")
else:
raise ValueError("Tried to greet an unhappy cat.")
Как правильно
В формате NumPy:
class Cat(Animal):
def greet(self, happy: bool = True):
"""Print a greeting from the cat.
Parameters
----------
happy : bool, optional
Whether the cat is happy, True by default.
Raises
------
ValueError
If the cat is not happy.
"""
if happy:
print("Meow!")
else:
raise ValueError("Tried to greet an unhappy cat.")
Или в формате Google:
class Cat(Animal):
def greet(self, happy: bool = True):
"""Print a greeting from the cat.
Args:
happy: Whether the cat is happy, True by default.
Raises:
ValueError: If the cat is not happy.
"""
if happy:
print("Meow!")
else:
raise ValueError("Tried to greet an unhappy cat.")
