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

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

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

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

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

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

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 in. general. Код ниже работает, но добавляет раздражающий $к имени параметра (потому что он был первоначально сделан для php).

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

Ответ 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 это помогает. Это работает как шарм, -)

Ответ 2

Вам нужно добавить восклицательный знак в начале Docstring 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

Ответ 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?"):

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

Ответ 4

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

Ответ 5

Yup, @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 (например, в начале функций или классов), используйте """!.

Ответ 6

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

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

>>> test(10)
10

Когда вы введете test(, появится ID-doc-tip с (arg: bool=False) -> None. Это было то, что я думал только о Visual Studio.

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