Как да документираме типовете параметри на функцията на 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 като цяло. Кодът по-долу работи, но добавя досаден $ към името на параметъра (защото първоначално е направен за 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) Форматът по подразбиране на docstrings в PyCharm е преструктуриран текст. Можете да го промените на Epytext (както в списъка на Tony Melony по-горе) във File-›Settings-›Python Integrate Tools-›Dostring Format. Вижте препратка към epydoc 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 е прав - това е (IMHO най-добрият) начин за комбиниране на двете схеми за документиране повече или по-малко безпроблемно. Ако, от друга страна, също искате да направите нещо като поставяне на текст на генерираната от 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