Как документировать метод с параметром(АМИ)? [закрытый]

поскольку docstrings являются свободной формой, это действительно зависит от того, что вы используете для анализа кода для создания документации API.

Я бы рекомендовал ознакомиться с Сфинкс разметки, поскольку он широко используется и становится стандартом де-факто для документирования проектов 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
   '''

эта разметка поддерживает перекрестные ссылки между документами и многое другое. Обратите внимание, что в документации Sphinx используется (например) :py:attr: в то время как вы можете просто использовать :attr: для документирования исходного кода.

естественно,есть и другие инструменты для документирования API. Есть более классический помощи Doxygen использует \paramкоманды но они специально не предназначены для документирования кода Python, такого как Sphinx есть.

обратите внимание, что есть аналогичный вопрос С аналогичный ответ здесь...

условные обозначения:

• PEP 257 Docstring Conventions
• PEP 287 reStructuredText Docstring Format

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

• Epydoc: автоматическое создание документации API для Python
• сфинкс.доб.Автодок – включать в документацию комментарии
• PyCharm имеет некоторую славную поддержку для комментарии

---

обновление: начиная с 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, могут легко воспользоваться им.

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 не применяет ни одно из них. Некоторые проекты имеют свои собственные соглашения. Некоторые инструменты для работы с docstrings также следуют определенным соглашениям.

Если вы планируете использовать Sphinx для документирования вашего кода, он способен создавать красиво отформатированные HTML-документы для ваших параметров с их функцией "подписи". http://sphinx-doc.org/domains.html#signatures

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

это, как говорится, я лично иду с встроенным стилем комментариев иногда.

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 всегда остаются вместе, что приносит следующие преимущества:
• меньше ввода (нет необходимости повторять имя переменной)
• более легкое обслуживание на изменять / извлекать переменную. Там никогда не будет какой-то бесхозный параметр doc абзац после переименования некоторых параметров.
• и легче найти недостающий комментарий.

теперь, некоторые могут подумать, что этот стиль выглядит "некрасиво". Но я бы сказать "уродливый" - это субъективное слово. Более нейтральный способ-сказать, что этот стиль не является мейнстримом, поэтому он может выглядеть менее знакомым вам, таким образом, менее удобным. Опять же," удобно " - это тоже субъективное слово. Но дело в том, что все описанные выше преимущества объективны. Вы не сможете достичь их, если будете следовать стандартным путем.

надеюсь, когда-нибудь в будущем, будет инструмент doc generator, который также может использовать такой встроенный стиль. Это будет управлять принятие.

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

Docstrings полезны только в интерактивных средах, например, оболочке 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

вы не можете делать такого рода вещи с Комментарии.