Как документировать типы параметров функции 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

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

Обновлять:

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

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

python doxygen
person sorin    schedule 07.10.2011    source источник
comment
Кажется, это то, что вы ищете: stack.nl/~dimitri /doxygen/docblocks.html#pythonblocks. Недостаточно информации? Что еще вы хотите?   -  person S.Lott    schedule 07.10.2011
comment
Лучшая документация, которую вы можете предоставить для входных и выходных данных, — это набор модульных тестов с использованием unittest фреймворк.   -  person Johnsyweb    schedule 10.10.2011
comment
@Johnsyweb ваша ссылка, к сожалению, не работает docs.python.org/2/library/unittest.html   -  person Kev1n91    schedule 04.03.2018
comment
7+ лет спустя docs.python.org/2/library/unittest.html или docs.python.org/3/library/unittest.html должен Работа.   -  person Johnsyweb    schedule 05.03.2018

Ответы (6)


arrow_upward
15
arrow_downward

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

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 это очень помогает. Работает как часы ;-)

person Tony Melony    schedule 21.03.2014
comment
Это не работает. Когда я добавил '!' после вступительных кавычек это сработало. - person SW_user2953243; 13.09.2014
comment
1) Чтобы создать документацию по функции, нажмите alt+Enter в заголовке функции и выберите вставить заглушку строки документации jetbrains.com/pycharm/webhelp/ 2) Форматом строк документации по умолчанию в PyCharm является реструктурированный текст. Вы можете изменить его на Epytext (как в приведенном выше списке Tony Melony) в File->Settings->Python Integrate Tools->Dostring Format. См. ссылку на эпидок epydoc.sourceforge.net/epytext.html. - person d9k; 08.11.2014

arrow_upward
6
arrow_downward

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

arrow_upward
4
arrow_downward

При использовании 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?"):

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

person robert    schedule 10.10.2011
comment
Но разве еще нет обработчиков документации, поддерживающих это, не так ли? Похоже, что сфинкс не, и я также ничего не могу найти о поддержке doxygen. - person naught101; 02.09.2014
comment
Три года назад я думал, что это было бы к настоящему времени. - person robert; 21.09.2014

arrow_upward
1
arrow_downward

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

person Tom    schedule 07.10.2011
comment
Основная причина в том, что проект уже использует doxygen, а во-вторых, sphinx не может документировать типы параметров. - person sorin; 10.10.2011

arrow_upward
1
arrow_downward

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

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

>>> test(10)
10

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

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

person Tcll    schedule 25.10.2017

arrow_upward
0
arrow_downward

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

person user147058    schedule 10.10.2013