Я пытаюсь задокументировать вызываемый класс Python с помощью строки документации, чтобы я мог автоматически генерировать документацию в Sphinx.
Я использую плагин autoDocstring для создания заглушек строк документации , Для классов, использующих метод __call__, кажется, что форматирование описания класса выглядит так, как если бы оно было функцией. Это добавляет поле :return: в строку документации Sphinx.
Это имеет смысл, как и тогда - при написании кода, который использует объект этого класса - Код Visual Studio показывает описание Класс, а не метод __call__:
Это нормально, но для этого необходимо, чтобы я задокументировал класс, как если бы он был функцией. Конечно, цель объектов вызываемых классов состоит в том, чтобы вести себя как функции, но у меня есть ощущение, что для строки документации класса неправильно иметь :return:. Поле :return:, очевидно, должно находиться в строке документации метода __call__, так как в противном случае оно может запутать менее опытных Python программистов, и в этом случае это не будет четкой документацией.
Вопросы :
- Должен ли я просто написать документирование класса для вызываемой, как если бы это была функция, сохраняя формат, предложенный плагином autoDocstring?
- Является ли это приемлемым стандартом для документирования классов с помощью * Метод 1031 * в Python?
Ниже вы найдете пример класса, использованного для создания снимка экрана выше.
class MultiplyBy:
"""Functor class for multiplying a number by fixed value
:return: Multiplied value
:rtype: float
"""
def __init__(self, multiplier: float) -> None:
"""Creates multiplier objects
Multiplier objects may be used to multipliy arbitratry number
by a fixed multiplier.
:param multiplier: Fixed multiplier value to be used for multiplying other numbers
:type multiplier: float
"""
self.multiplier = multiplier
def __call__(self, value: float) -> float:
"""Multiplies a number by a fixed value
Returns a number being the value provided multiplied
by a fixed value specified at the multiplier object construction time.
:param value: The value to be multiplied
:type value: float
:return: The value multiplied by the fixed multiplier
:rtype: float
"""
return value * self.multiplier
И код sample.py
from multiplier import MultiplyBy
double = MultiplyBy(2.0)
doubled = double(5.0)