파라미터로 메소드를 문서화하는 방법은 무엇입니까?

파이썬의 문서 문자열을 사용하여 매개 변수로 메소드를 문서화하는 방법은 무엇입니까?

편집 : 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
    ...

이것은 대부분의 파이썬 개발자들이 사용하는 규칙입니까?

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

내 경험을 바탕으로, NumPy와 문서화 문자열 규칙은 (PEP257 상위) 가장 널리 확산되어 다음 또한 다음과 같은 도구가 지원하는 규칙 스핑크스 .

한 가지 예 :

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

docstring은 자유 형식이므로 코드를 구문 분석하여 API 문서를 생성하는 데 사용하는 내용에 따라 달라집니다.

Sphinx 마크 업에 익숙해지는 것이 좋습니다. 널리 사용되며 부분적으로 우수한 readthedocs.org 서비스로 인해 Python 프로젝트를 문서화하기위한 사실상의 표준이되었습니다 . Sphinx 문서 의 예제 를 파이썬 스 니펫으로 바꾸어 표현 하려면 :

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 이 있지만 Sphinx와 같은 Python 코드를 문서화하도록 특별히 설계되지 않았습니다.\param

여기에 비슷한 대답 이있는 비슷한 질문 이 있습니다.

컨벤션 :

• PEP 257 Docstring Conventions
• PEP 287 reStructuredText 문서 문자열 형식

도구 :

• Epydoc : Python을위한 자동 API 문서 생성
• sphinx.ext.autodoc – docstring의 문서 포함
• PyCharm은 docstring을 훌륭하게 지원합니다.

업데이트 : 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과 같은 도구가 쉽게 활용할 수 있다는 것입니다.

파이썬 doc 문자열은 자유 형식 이며 원하는 방식으로 문서화 할 수 있습니다.

예 :

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

이제 몇 가지 규칙이 있지만 파이썬은 어떤 규칙도 시행하지 않습니다. 일부 프로젝트에는 자체 규칙이 있습니다. docstring과 함께 작동하는 일부 도구는 특정 규칙을 따릅니다.

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가 이미 다른 의견에서 지적했듯이 이점은 다음과 같습니다.

• 가장 중요한 것은 매개 변수와 해당 문서가 항상 함께 유지되므로 다음과 같은 이점이 있습니다.
• 타이핑이 적음 (변수 이름을 반복 할 필요 없음)
• 변수 변경 / 제거시 손쉬운 유지 보수. 일부 매개 변수의 이름을 바꾼 후에는 고아 매개 변수 문서 단락이 없습니다.
• 누락 된 댓글을 쉽게 찾을 수 있습니다.

이제 일부 사람들은이 스타일이 "못 생겼다"고 생각할 수도 있습니다. 그러나 "추악한"은 주관적인 단어입니다. 더 깔끔한 방법은이 스타일이 주류가 아니기 때문에 익숙하지 않아서 덜 편안 할 수 있다는 것입니다. "편안한"또한 주관적인 단어입니다. 그러나 요점은 위에서 설명한 모든 이점이 객관적이라는 것입니다. 표준 방식을 따르면 달성 할 수 없습니다.

앞으로 언젠가는 이러한 인라인 스타일을 사용할 수있는 문서 생성기 도구가있을 것입니다. 그것은 채택을 이끌 것입니다.

추신 :이 답변은 내가 맞을 때마다 인라인 주석을 사용하는 것을 선호합니다. 동일한 인라인 스타일을 사용하여 사전 도 문서화합니다 .

매개 변수 유형을 문서화하는 더 나은 구조화 된 방법을 제공하는 유형 힌트 응답 ( 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/ 에서 채택한 예

Docstring은 대화 형 환경 (예 : 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

docstrings로는 이런 종류의 일을 할 수 없습니다.