Как документировать типы параметров функции Python?

Question

Я знаю, что параметрами может быть любой объект, но для документации очень важно указать, что вы ожидаете.

Во-первых, как указать типы параметров, подобные приведенным ниже?

• str (или используйте String или string?)
• int
• list
• dict
• функция ()
• tuple
• экземпляр объекта класса MyClass

Во-вторых, как указать параметры, которые могут быть нескольких типов, например, функция, которая может обрабатывать один параметр, который может быть int или str?

Пожалуйста, используйте приведенный ниже пример, чтобы продемонстрировать синтаксис, необходимый для документирования этого с вашим предлагаемым решением. Имейте в виду, что желательно иметь возможность ссылаться на ссылку на класс «Image» из документации.

def myMethod(self, name, image):
    """
    Does something ...

    name String: name of the image
    image Image: instance of Image Class or a string indicating the filename.

    Return True if operation succeeded or False.
    """
    return True

Обратите внимание, вы можете предложить использовать любой инструмент документирования (сфинкс, кислород, ...), если он способен соответствовать требованиям.

Обновление:

Похоже, что есть некоторая поддержка для документирования типов параметров в doxygen в общем. Приведенный ниже код работает, но добавляет раздражающее значение $ к имени параметра (поскольку оно изначально было создано для php).

    @param str $arg description
    @param str|int $arg description

Answer 1

Есть лучший способ.Мы используем

def my_method(x, y):
    """
    my_method description

    @type x: int
    @param x: An integer

    @type y: int|string
    @param y: An integer or string

    @rtype: string
    @return: Returns a sentence with your variables in it
    """

    return "Hello World! %s, %s" % (x,y)

Вот и все.В PyCharm IDE это очень помогает.Это работает как шарм; -)

Answer 2

Вам нужно добавить восклицательный знак в начале строки документации Python для Doxygen, чтобы правильно его проанализировать.

def myMethod(self, name, image):
    """!
    Does something ...

    @param name String: name of the image
    @param image Image: instance of Image Class or a string indicating the filename.

    @return Return True if operation succeeded or False.
    """
    return True

Answer 3

При использовании Python 3 вы можете использовать аннотации функций, описанные в PEP 3107 .

def compile(
   source: "something compilable",
   filename: "where the compilable thing comes from",
   mode: "is this a single statement or a suite?"):

См. Также определения функций .

Answer 4

Doxygen отлично подходит для C ++, но если вы работаете в основном с кодом на Python, вам следует попробовать sphinx .Если вы выбираете сфинкса, то все, что вам нужно сделать, это следовать pep8 .

Answer 5

Подумал, что я опубликую этот маленький кусочек здесь, поскольку IDEA показала мне, что это возможно, и мне никогда не рассказывали и не читали об этом.

>>> def test( arg: bool = False ) -> None: print( arg )

>>> test(10)
10

Когда вы набираете test(, документ-подсказка IDLEпоявляется с (arg: bool=False) -> None Что я думал, что только Visual Studio сделал.

Это не совсем материал для кислорода, но он хорошо подходит для документирования типов параметров для тех, кто использует ваш код.

Answer 6

Да, @docu прав - это (ИМХО лучший) способ более или менее плавного объединения обеих схем документации.Если, с другой стороны, вы также хотите сделать что-то вроде размещения текста на странице индекса, генерируемой doxygen, вы должны добавить

##
# @mainpage (Sub)Heading for the doxygen-generated index page
# Text that goes right onto the doxygen-generated index page

где-нибудь в начале вашего кода Python.

Другими словами, если doxygen не ожидает комментариев Python, используйте ##, чтобы предупредить его о наличии тегов для него.Там, где ожидаются комментарии Python (например, в начале функций или классов), используйте """!.