Python 패키지 개발일지 05: 주석을 이용한 문서화

특정한 위치에 있는 블록 주석은 요소의 __doc__속성이 되어 IntelliSense나 Sphinx등이 자동으로 설명을 붙일 수 있도록 해줍니다. 개발자가 아닌 사용자를 위한 이 주석은 별도로 docstring이라고 부르기도 합니다. 여기서는 Sphinx가 참조하는 구글 스타일의 주석과, Numpy스타일의 주석을 살펴봅니다.

Docstring

def function(a):
    """이것은 함수입니다.

    Args:
        a: 매개변수로 뭔가를 받습니다.

    Returns:
        뭔가를 반환합니다.
    """
    return a

if __name__ == "__main__":
    print(function.__doc__)

지능형 코드 완성(IntelliSense) 기능을 제공하는 편집기는 이 __doc__를 자동으로 읽어 사용자에게 팝업시켜 보여줍니다.

문서화 문자열의 위치

__doc__의 내용으로 인식하는 주석의 특별한 위치들이 있습니다.

모듈과 패키지

"""모듈의 간략한 설명.

모듈
====

모듈의 경우 문서의 최상단에 있는 주석을 모듈의 문서화 문자열(docstring)로
인식합니다.

패키지
======

이 문서화 문자열이 패키지의 `__init__.py`에 있다면 파이썬은 이것을
패키지의 문서화 문자열로 인식합니다.
"""
import os
import sys

...소스코드...

많은 경우 문서화 문자열을 읽는 기능을 가진 응용프로그램이나 패키지는 마크다운을 지원합니다. 마크다운 문법은 변환을 거치지 않은 상태라고 해도 읽기에 큰 문제가 없으므로 가능하면 마크다운으로 작성하는 것을 염두해 두는 것을 추천합니다.

함수와 클래스

def function(arg):
    """함수의 간단한 설명

    자세한 설명...
    """
    return out

class MyClass:
    """클래스 설명

    `__init__`과 관련한 설명도 이곳에 씁니다.
    """
    def __init__(self, arg):
        """init은 보통 설명이 보일 일이 없습니다."""

    def method(self, arg):
        """멤버 함수에 대한 간략한 설명.

        멤버함수에 대한 자세한 설명...
        """
        return out

스타일 살펴보기

구글 스타일은 문서화 문자열을 넓게 쓰고, Numpy 스타일은 문서화 문자열을 길게 쓴다는 차이가 있습니다. 하지만 작성하는 사람이 보기 쉽고 쓰기 쉽다면 어떤 형식이라도 괜찮습니다.

구글 스타일

"""구글 스타일 문서화 문자열.

구글 스타일
===========

제목을 정할 때는 기존과 같습니다. `==`로 제목을 `--`로 소제목을
표현합니다. `참고해야 할 하이퍼링크`_ 가 있다면 아래에 url 정의를
할 수 있습니다.

.. _참고해야 할 하이퍼링크:
    https://soma0sd.tistory.com/

Attributes:
    module_variable_1(int): 모듈 수준의 변수가 있는 경우 모듈의
      문서화 문자열에 `Attributes:` 섹션을 만들어서 표현합니다.

Example:
    예시를 기록합니다.

Todo:
    * 앞으로 할 것의 목록
    * `Todo`는 모듈이나 패키지, 함수, 클래스 등에 자유롭게
        사용할 수 있습니다.
    * 사용자 입장에서 서술하는 것이 좋습니다.
"""

def function(arg1: int, arg2: str) -> bool:
    """함수의 문서화 문자열.

    Args:
        arg1 (int): 사실 함수에 이미 매개변수 형태가 있다면
            굳이 괄호로 표시해 줄 필요는 없습니다.
        arg2: 들여쓰기와 콜론(`:`)이 매개변수와 설명을
            구분합니다.

    Returns:
        bool: 이 경우에도 형태가 소스코드에 이미 있다면
            굳이 반복해서 쓸 필요는 없습니다.

    Raises:
        AttributeError: 예외 설명이 필요한 경우.

    Yields:
        출력값이 무언가를 나열하는 경우.

    Note:
        함께 알아두어야 할 사항이 있는 경우.

    `Args`나 `Returns` 등 각 섹션 사이에는 빈 줄이 하나 필요합니다.
    """
    return True

Numpy

"""넘파이 스타일 문서화 문자열.

Numpy 스타일
=============

제목을 정할 때는 기존과 같습니다. `==`로 제목을 표현합니다.
`참고해야 할 하이퍼링크`_ 가 있다면 아래에 url 정의를
할 수 있습니다.

.. _참고해야 할 하이퍼링크:
    https://soma0sd.tistory.com/

Attributes
-----------
module_variable_1(int): 모듈 수준의 변수가 있는 경우 모듈의
  문서화 문자열에 `Attributes:` 섹션을 만들어서 표현합니다.

Todo
-----
* 앞으로 할 것의 목록
* `Todo`는 모듈이나 패키지, 함수, 클래스 등에 자유롭게
    사용할 수 있습니다.
* 사용자 입장에서 서술하는 것이 좋습니다.
"""

def function(arg1: int, arg2: str) -> bool:
    """함수의 문서화 문자열.

    Parameters
    ----------
    arg1 (int)
        사실 함수에 이미 매개변수 형태가 있다면
        굳이 괄호로 표시해 줄 필요는 없습니다.
    arg2
        줄바꿈과 들여쓰기로 섹션을 구분합니다.

    Returns
    --------
    bool
        이 경우에도 형태가 소스코드에 이미 있다면
        굳이 반복해서 쓸 필요는 없습니다.

    Raises
    -------
    AttributeError
        예외 설명이 필요한 경우.

    Yields
    -------
    출력값이 무언가를 나열하는 경우.

    Note
    ----
    함께 알아두어야 할 사항이 있는 경우.

    `Args`나 `Returns` 등 각 섹션 사이에는 빈 줄이 하나 필요합니다.
    """
    return True