Строка документации для вызываемого класса в Python - PullRequest
Новая
       14

Строка документации для вызываемого класса в Python

1 голос
/ 04 марта 2020

Я пытаюсь задокументировать вызываемый класс Python с помощью строки документации, чтобы я мог автоматически генерировать документацию в Sphinx.

Я использую плагин autoDocstring для создания заглушек строк документации , Для классов, использующих метод __call__, кажется, что форматирование описания класса выглядит так, как если бы оно было функцией. Это добавляет поле :return: в строку документации Sphinx.

Это имеет смысл, как и тогда - при написании кода, который использует объект этого класса - Код Visual Studio показывает описание Класс, а не метод __call__:

enter image description here

Это нормально, но для этого необходимо, чтобы я задокументировал класс, как если бы он был функцией. Конечно, цель объектов вызываемых классов состоит в том, чтобы вести себя как функции, но у меня есть ощущение, что для строки документации класса неправильно иметь :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)
...