programing

매개 변수를 사용하여 메서드를 문서화하려면 어떻게 해야 합니까?

goodsources 2022. 10. 10. 18:33
반응형

매개 변수를 사용하여 메서드를 문서화하려면 어떻게 해야 합니까?

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

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

docstring은 자유 형식이기 때문에 API 문서를 생성하기 위해 코드를 해석하기 위해 무엇을 사용하는지에 따라 달라집니다.

Sphinx 마크업은 널리 사용되고 있으며 Python 프로젝트를 문서화하는 데 있어 디커버링 표준이 되고 있기 때문에 나는 Sphinx 마크업에 익숙해지는 것을 추천한다.부분적으로는 훌륭한 readthedocs.org 서비스 때문이다.Sphinx 설명서의 를 Python 스니펫으로 바꾸려면:

def send_message(sender, recipient, message_body, priority=1) -> int:
   """
   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를 문서화하는 다른 툴도 있습니다.고전적인 독시겐이 있는데\param 명령어는 Sphinx처럼 Python 코드를 문서화하기 위해 특별히 설계되지 않았습니다.

여기에도 비슷한 질문과 비슷한 답변이 있습니다.

지금까지의 경험에 비추어 볼 때, Numpy docstring 규칙(PEP257 superset)은 스핑크스와 같은 툴에서도 지원되는 가장 광범위한 규칙입니다.

한 가지 예:

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

표기법:

도구:


업데이트: Python 3.5에서 기계에서 읽을 수 있는 컴팩트한 구문인 type hints를 사용할 수 있습니다.

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
    """

몇 가지 관례가 있지만 비단뱀은 그 어느 것도 강요하지 않습니다.일부 프로젝트에는 고유한 규칙이 있습니다.docstring을 사용하기 위한 일부 도구도 특정 규칙을 따릅니다.

스핑크스를 사용하여 코드를 문서화할 계획이라면 파라미터에 적합한 형식의 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/

문서 문자열은 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

이런 종류의 일은 문서스트링으로는 할 수 없다.

언급URL : https://stackoverflow.com/questions/9195455/how-to-document-a-method-with-parameters

반응형