Як документувати метод за допомогою параметрів?


139

Як документувати методи з параметрами за допомогою рядків документації Python?

EDIT: PEP 257 дає такий приклад:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

Це умова, яку використовують більшість розробників Python?

Keyword arguments:
<parameter name> -- Definition (default value if any)

Я очікував чогось трохи більш формального, такого як

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    @param: real The real part (default 0.0)
    @param: imag The imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

Навколишнє середовище : Python 2.7.1


1
Ви читали PEP 257? python.org/dev/peps/pep-0257
NPE

1
Там є кілька «стандартів», але щодо практичного підходу, і особливо якщо вам подобається щось формальне, я б рекомендував сфінкс . Його інтеграція в Pycharm робить генерування добре структурованих доктрин досить безболісним. ІМХО
жоджо

Відповіді:


86

Виходячи з мого досвіду, конвенції про докстринг numpy (суперсет PEP257) - це найбільш широко розповсюджені конвенції, що слідують , які також підтримуються інструментами, такими як Sphinx .

Один приклад:

Parameters
----------
x : type
    Description of parameter `x`.

2
Це ближче до того, що я очікував. На жаль, я вибрав звичайний PEP 257 і додав власну умову (ціною втрати автогенерованої HTML / PDF документації). Однак наступного разу я підберу це рішення. Дякую.
Девід Андреолетті

5
Коли я намагаюся обробити запропонований вами докстринг, Сфінкс скаржиться SEVERE: Unexpected section title- чи знаєте ви якийсь спосіб зробити Сфінкс щасливішим?
Брендон Родос

@BrandonRhodes це посилання говорить про використання цих конвенцій зі сфінксом: github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
Володимир Келешев

3
Насправді раніше місця не вистачає Description. Я перевірив нумеровану документацію, бо одразу помітив і подумав: "Зачекайте секунду, чому це три пробіли? Це дивно. Хто б використовував три пробіли?"
Зельфір Кальтшталь

6
Можливо, це була найкраща відповідь на той момент, коли питання було задано, але я думаю, що зараз (наприкінці 2017 року) Сфінкс виявився переможним.
Alex L

120

Оскільки docstrings є вільною формою, це дійсно залежить від того, що ви використовуєте для розбору коду для створення документації API.

Я рекомендую ознайомитись з розміткою Sphinx , оскільки вона широко використовується і стає фактичним стандартом для документування проектів Python, частково через чудовий сервіс readthedocs.org . Щоб перефразувати приклад з документації Сфінкса в якості сниппета Python:

def send_message(sender, recipient, message_body, priority=1):
   '''
   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring
   '''

Ця розмітка підтримує перехресне посилання між документами та іншим. Зауважте, що документація на Сфінкс використовує (наприклад), :py:attr:тоді як ви можете просто використовувати їх :attr:для документування з вихідного коду.

Природно, є й інші інструменти для документування API. Є більш класичний Doxygen, який використовує \param команди, але вони не розроблені спеціально для документування коду Python, як Sphinx.

Зауважте, що тут є аналогічне запитання із подібною відповіддю ...


9
Це стиль, який за замовчуванням використовує автогенерація коментарів PyCharm
Josiah Yoder

Що з синтаксисом складених типів, як списки речей?
matanster

то це а list.
anarcat

33

Конвенції:

Інструменти:


Оновлення: з Python 3.5 ви можете використовувати підказки типу, що є компактним, машиночитаним синтаксисом:

from typing import Dict, Union

def foo(i: int, d: Dict[str, Union[str, int]]) -> int:
    """
    Explanation: this function takes two arguments: `i` and `d`.
    `i` is annotated simply as `int`. `d` is a dictionary with `str` keys
    and values that can be either `str` or `int`.

    The return type is `int`.

    """

Основна перевага цього синтаксису полягає в тому, що він визначається мовою і що він є однозначним, тому такі інструменти, як PyCharm, можуть легко скористатися з нього.


12
Незважаючи на те, що ця відповідь зараз є найбільш сприятливою, жоден з вищезгаданих PEP не передбачає конвенції для визначення типів аргументів методу.
коріандр

11

Струни python doc є вільною формою , їх можна документувати будь-яким способом.

Приклади:

def mymethod(self, foo, bars):
    """
    Does neat stuff!
    Parameters:
      foo - a foo of type FooType to bar with.
      bars - The list of bars
    """

Зараз є деякі умовності, але python не виконує жодної з них. Деякі проекти мають свої конвенції. Деякі інструменти для роботи з документами також відповідають певним умовам.


8

Якщо ви плануєте використовувати Sphinx для документування свого коду, він може створити добре відформатовані HTML-документи для ваших параметрів з їх функцією 'підписи'. http://sphinx-doc.org/domains.html#signatures


3

Як вже вказувалося на інші відповіді тут, основний потік, ймовірно, йде шляхом Сфінкса, щоб згодом ви могли використовувати Sphinx для створення цих вигадливих документів.

Попри це, я особисто час від часу переходжу до стилю вбудованого коментаря.

def complex(  # Form a complex number
        real=0.0,  # the real part (default 0.0)
        imag=0.0  # the imaginary part (default 0.0)
        ):  # Returns a complex number.
    """Form a complex number.

    I may still use the mainstream docstring notation,
    if I foresee a need to use some other tools
    to generate an HTML online doc later
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    other_code()

Ще один приклад тут, з невеликими деталями, документально підтвердженими:

def foo(  # Note that how I use the parenthesis rather than backslash "\"
          # to natually break the function definition into multiple lines.
        a_very_long_parameter_name,
            # The "inline" text does not really have to be at same line,
            # when your parameter name is very long.
            # Besides, you can use this way to have multiple lines doc too.
            # The one extra level indentation here natually matches the
            # original Python indentation style.
            #
            # This parameter represents blah blah
            # blah blah
            # blah blah
        param_b,  # Some description about parameter B.
            # Some more description about parameter B.
            # As you probably noticed, the vertical alignment of pound sign
            # is less a concern IMHO, as long as your docs are intuitively
            # readable.
        last_param,  # As a side note, you can use an optional comma for
                     # your last parameter, as you can do in multi-line list
                     # or dict declaration.
        ):  # So this ending parenthesis occupying its own line provides a
            # perfect chance to use inline doc to document the return value,
            # despite of its unhappy face appearance. :)
    pass

Переваги (як @ mark-horvath вже вказувалося в іншому коментарі):

  • Найголовніше, що параметри та їх документ завжди залишаються разом, що приносить наступні переваги:
  • Менше набору тексту (не потрібно повторювати назву змінної)
  • Легше обслуговування після зміни / видалення змінної. Після перейменування якогось параметра не буде жодного параграфа в документі-сироті.
  • і простіше знайти пропущений коментар.

Зараз дехто може подумати, що цей стиль виглядає «потворно». Але я б сказав "потворне" - це суб'єктивне слово. Більш нейтральний спосіб сказати, що цей стиль не є мейнстрімом, тому він може виглядати вам менш звично, таким чином, менш комфортним. Знову ж таки, «комфортно» - це теж суб’єктивне слово. Але справа в тому, що всі переваги, описані вище, є об'єктивними. Ви не можете їх досягти, якщо слідувати стандартному шляху.

Сподіваємось, в якийсь день у майбутньому з'явиться інструмент генератора doc, який також може споживати такий стиль вбудованої форми. Це призведе до усиновлення.

PS: Ця відповідь випливає з мого власного вподобання використовувати вбудовані коментарі, коли я вважаю за потрібне. Я використовую один і той же стиль вбудовування для документування словника .


1

Спираючись на відповідь на підказки типу ( https://stackoverflow.com/a/9195565/2418922 ), який забезпечує кращий структурований спосіб документування типів параметрів, існує також структурований спосіб документування як типу, так і описів параметрів:

def copy_net(
    infile: (str, 'The name of the file to send'),
    host: (str, 'The host to send the file to'),
    port: (int, 'The port to connect to')):

    pass

Приклад прийнятий з: https://pypi.org/project/autocommand/


1
Це офіційний синтаксис? Його супер корисно, проте я не можу знайти його в офіційних документах / PEPs ...
Офрі Равів

1
Я також хотів би це знати, якщо для цього є ПЕП.
DreamFlasher

-1

Документи є корисними лише в інтерактивних середовищах, наприклад, оболонці Python. Під час документування об'єктів, які не будуть використовуватися інтерактивно (наприклад, внутрішні об'єкти, зворотний зв'язок рамки), ви також можете використовувати регулярні коментарі. Ось стиль, який я використовую для підвішування відступних коментарів на предмет, кожен у своєму рядку, тож ви знаєте, що коментар стосується:

def Recomputate \
  (
    TheRotaryGyrator,
      # the rotary gyrator to operate on
    Computrons,
      # the computrons to perform the recomputation with
    Forthwith,
      # whether to recomputate forthwith or at one's leisure
  ) :
  # recomputates the specified rotary gyrator with
  # the desired computrons.
  ...
#end Recomputate

Ви не можете робити подібні речі з документами.


46
О, це виглядає некрасиво.
Міша Акованцев

1
Потворне так? Цікава ідея ... також так.
Девід

2
Вбудовані коментарі до змінних дуже чутливі, менше вводити текст (не потрібно повторювати ім'я змінної), легше обслуговування при зміні / видаленні змінної ... простіше знайти відсутні коментарі. Поєднав би його з належним docstring під підписом. +1
Марк Хорват

Це не працює як документація. Якщо ви прокоментуєте такий пакунок, як цей, і користувач PyCharm завантажує його, він не зможе перевірити, що робить кожен парам, не отримавши доступ до вашої документації - чого ви не зможете генерувати за допомогою будь-якого програмного забезпечення. Якщо ви не зробите своє. Ось чому ОП просить уточнити його в docstring. Вибачте так пізно.

Це просто жахливо.
Майкл Уолтерс
Використовуючи наш веб-сайт, ви визнаєте, що прочитали та зрозуміли наші Політику щодо файлів cookie та Політику конфіденційності.
Licensed under cc by-sa 3.0 with attribution required.