Как документировать метод с параметрами?

Ответ 1

Исходя из моего опыта, условные соглашения о документах (суперсет PEP257) являются наиболее распространенными соглашениями, которые также поддерживаются такими инструментами, как Sphinx.

Один пример:

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

Ответ 2

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

Я бы порекомендовал ознакомиться с разметкой Sphinx, поскольку она широко используется и становится стандартом де-факто для документирования проектов Python, отчасти из-за отличного сервиса readthedocs.org. Перефразируя пример из документации по Sphinx в виде фрагмента 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.

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

Ответ 3

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

• Соглашения Poc 257 Docstring
• PEP 287 reStructuredText Формат Docstring

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

• Epydoc: автоматическое создание документации API для Python
• sphinx.ext.autodoc - Включить документацию из docstrings
• PyCharm имеет хорошую поддержку для docstrings

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

Ответ 4

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

Ответ 5

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

Ответ 6

Основной поток, как уже указывалось в других ответах, вероятно, идет по пути Sphinx, чтобы вы могли использовать 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 уже указывалось в другом комментарии):

• Самое главное, что параметры и их документ всегда остаются вместе, что дает следующие преимущества:
• Меньше ввода (не нужно повторять имя переменной)
• Более простое обслуживание при смене/удалении переменной. После переименования какого-либо параметра никогда не будет какого-либо абзаца с документом-параметром.
• и легче найти пропущенный комментарий.

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

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

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

Ответ 7

Докстры используются только в интерактивных средах, например. оболочки Python. При документировании объектов, которые не будут использоваться в интерактивном режиме (например, внутренние объекты, обратные вызовы структуры), вы можете также использовать регулярные комментарии. Heres стиль, который я использую для зависания отступов комментариев от элементов, каждый на своей собственной линии, так что вы знаете, что комментарий применяется к:

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 leisure
  ) :
  # recomputates the specified rotary gyrator with
  # the desired computrons.
  ...
#end Recomputate

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