Python Docstrings: Viết tài liệu cho code

Mô tả

Docstring (Documentation String) là chuỗi literal đặt ngay sau định nghĩa function, class, module, method. Truy cập qua thuộc tính __doc__.

1. Docstring một dòng

def add_nums(x):
    '''Cộng một số với chính nó.'''
    return x + x

print(add_nums.__doc__)  # Cộng một số với chính nó.

2. Docstring nhiều dòng (PEP 257)

Cấu trúc: Dòng tóm tắt → dòng trống → mô tả chi tiết.

def fibonacci(n):
    '''Trả về số Fibonacci thứ n.
    
    Args:
        n (int): Vị trí trong dãy Fibonacci (n >= 0).
    
    Returns:
        int: Số Fibonacci thứ n.
    
    Examples:
        >>> fibonacci(0)
        0
        >>> fibonacci(5)
        5
    '''
    if n <= 1:
        return n
    a, b = 0, 1
    for _ in range(n - 1):
        a, b = b, a + b
    return b

print(fibonacci.__doc__)

3. Docstring của built-in objects

print(list.__doc__)
# Built-in mutable sequence...
print(len.__doc__)
# Return the number of items in a container.

4. Thụt lề trong Docstring

• Dòng 1: Thụt lề không quan trọng, bị bỏ qua.
• Các dòng sau: Thụt lề tương đối được giữ nguyên.
• Công cụ như inspect.cleandoc() hoặc textwrap.dedent() chuẩn hóa thụt lề.

def example():
    '''
    Dòng 1: không thụt lề.
      Dòng 2: thụt 2 space.
        Dòng 3: thụt 4 space.
    Dòng 4: không thụt lề.
    '''
    pass

import inspect
print(repr(inspect.cleandoc(example.__doc__)))

5. Công cụ xử lý Docstring

• help(obj): In docstring đẹp mắt.
• pydoc: Tạo tài liệu HTML.
• Sphinx: Generator tài liệu chuyên nghiệp (dùng reST/Markdown).
• doctest: Test code trong docstring.