docstring의 세 가지 스타일

 이번 포스팅에서는 docstring 작성에 주로 사용되는 세 가지 스타일 reStructuredText, Google style, Numpy style에 대해서 간략하게 알아보고자한다.

 

reStructuredText

---

def func(arg1, arg2, arg3):
  """Hello, func

  Lorem ipsum dolor sit amet, 

  :param string arg1: First argument
  :param arg2: Second argument
  :type args2: list[int]
  :param arg3: Third argument
  :type args3: dict[str, int]
  :return: Return value
  :rtype: str or None
  :raises ValueError: if arg1 is empty string.
  """

• param, parameter, arg, argument, ket, keword : 인수의 설명
• type : 인수의 데이터 형
• raises, raise, except, exception : 예외(언제 예외가 발생하는가?)를 정의
• var, ivar, cvar : 변수의 설명
• vartype : 변수의 데이터형
• returns, return : 반환 값에 대한 설명
• rtype : 반환값의 데이터 형

 

 

Google style

---

def func(arg1, arg2, arg3):
  """Hello, func

  Lorem ipsum dolor sit amet, 

  Args:
    arg1 (str): First argument
    arg2 (list[int]): Second argument
    arg3 (dict[str, int]): Third argument

  Returns:
    str or None: Return value

  Raises:
    ValueError: if arg1 is empty string.
  """

• Args: 각 변수의 목록을 기재. 이름뒤에 클론과 스페이스를 구분해 설명은 작성한다. 설명이 80개의 문자이내로 끝나지 않은 경우 다음행에 띄어쓰기 2개나 4개로 구분해서 계속해서 작성한다.
• Returns: 데이터형과 반환 값의 시멘틱스를 설명한다. 함수에서 None만 반환되는 경우, 이 섹션을 불필요하다.
• Raises: 인터페이스와 관련된 모든 예외 목록을 기재한다.

섹션 목록

• Args (alias of Parameters)
• Arguments (alias of Parameters)
• Attributes
• Example
• Examples
• Keyword Args (alias of Keyword Arguments)
• Keyword Arguments
• 메소드
• Note
• Notes
• Other Parameters
• Parameters
• Return (alias of Returns)
• Returns
• Raises
• References
• See Also
• 과제
• Warning
• Warnings (alias of Warning)
• Warns
• Yield (Yields의 다른 이름)
• Yields

 

 

Numpy style

---

def func(arg1, arg2, arg3):
  """Hello, func

  Lorem ipsum dolor sit amet, 

  Parameters
  -------
  arg1 : str
    First argument
  arg2 : list[int]
    Second argument
  arg3 : dict[str, int]
    Third argument

  Returns
  -------
  str or None
    Return value

  Raises
  -------
  ValueError
    if arg1 is empty string.
  """

자세한 내용은 공식 문서를 확인하길 바란다.

---

참고자료

https://qiita.com/yokoc1322/items/ebf25c9cb779ff5ebc9c