9. 파이썬 문서 문자열 (Docstring)

Docstring에 대해서 알아보자

파이썬에서 문서 문자열(Docstring)은 함수, 클래스, 모듈 등의 설명을 포함하는 문자열이다. 이 문자열은 해당 코드 요소의 첫 번째 줄에 위치하며, 주석과 달리 코드의 일부분으로 간주되어 __doc__ 속성을 통해 접근할 수 있다. 문서 문자열을 통해 코드의 기능과 사용법을 쉽게 이해할 수 있도록 도움을 준다.

1. 기본 문법

문서 문자열은 큰따옴표 세 개(""" """)나 작은따옴표 세 개(''' ''')로 둘러싸여 작성된다. 일반적으로 큰따옴표 세 개를 사용하는 것이 관례이다.

def function():
    """
    이 함수는 예제 함수입니다.
    자세한 설명은 여기에 작성합니다.
    """
    pass

2. 함수의 문서 문자열

함수에 대한 문서 문자열은 함수의 기능, 매개변수, 반환 값 등을 설명하는 데 사용된다.

def add(a, b):
    """
    두 수를 더한 값을 반환하는 함수입니다.

    매개변수:
    a (int): 첫 번째 숫자
    b (int): 두 번째 숫자

    반환 값:
    int: 두 수의 합
    """
    return a + b

print(add.__doc__)

3. 클래스의 문서 문자열

클래스에 대한 문서 문자열은 클래스의 목적, 속성, 메서드 등을 설명하는 데 사용된다.

class Person:
    """
    사람을 나타내는 클래스입니다.

    속성:
    name (str): 사람의 이름
    age (int): 사람의 나이
    """

    def __init__(self, name, age):
        """
        Person 클래스의 생성자입니다.

        매개변수:
        name (str): 사람의 이름
        age (int): 사람의 나이
        """
        self.name = name
        self.age = age

    def greet(self):
        """
        인사 메시지를 출력하는 메서드입니다.
        """
        print(f"안녕하세요, 제 이름은 {self.name}입니다.")

print(Person.__doc__)
print(Person.__init__.__doc__)
print(Person.greet.__doc__)

4. 모듈의 문서 문자열

모듈에 대한 문서 문자열은 모듈의 목적과 사용법을 설명하는 데 사용된다. 모듈의 첫 번째 줄에 위치해야 한다.

"""
이 모듈은 예제 모듈입니다.
모듈의 기능과 사용법을 설명합니다.
"""

def example_function():
    """
    이 함수는 예제 함수입니다.
    """
    pass

5. 접근 방법

문서 문자열은 해당 코드 요소의 __doc__ 속성을 통해 접근할 수 있다.

def multiply(a, b):
    """
    두 수를 곱한 값을 반환하는 함수입니다.

    매개변수:
    a (int): 첫 번째 숫자
    b (int): 두 번째 숫자

    반환 값:
    int: 두 수의 곱
    """
    return a * b

# 함수의 문서 문자열 접근
print(multiply.__doc__)

class Animal:
    """
    동물을 나타내는 클래스입니다.
    """

    def __init__(self, species, name):
        """
        Animal 클래스의 생성자입니다.

        매개변수:
        species (str): 동물의 종
        name (str): 동물의 이름
        """
        self.species = species
        self.name = name

    def speak(self):
        """
        동물이 소리를 내는 메서드입니다.
        """
        print(f"{self.name}가 소리를 냅니다.")

# 클래스의 문서 문자열 접근
print(Animal.__doc__)
print(Animal.__init__.__doc__)
print(Animal.speak.__doc__)

6. 문서 문자열의 활용

문서 문자열은 코드의 가독성을 높이고, 코드 유지 보수를 용이하게 한다. 또한, 도구를 사용하여 자동으로 문서화를 생성할 때 사용된다. 예를 들어, pydoc은 문서 문자열을 기반으로 자동으로 HTML 문서를 생성할 수 있다.

pydoc -w example_module