Python 文档注释（Docstring）

一、与 Java 文档注释的对比

特性	Java JavaDoc	Python Docstring
语法	/** ... */	"""..."""（三重引号）
位置	类/方法前	模块、类、函数的第一行
运行时访问	编译后丢弃（需特殊注解保留）	通过 __doc__ 属性直接访问
标准工具	javadoc	Sphinx、pdoc、mkdocstrings

运行时可用

def add(a, b):
    """返回两数之和。"""
    return a + b

# 运行时直接访问（Java 做不到）
print(add.__doc__)  # 输出: 返回两数之和。
help(add)           # 显示完整文档

# inspect 模块内省（标准库支持）
import inspect
print(inspect.getdoc(add))

二、三种主流文档风格

风格 1：Sphinx/reStructuredText（最接近 JavaDoc）

使用 :param:、:return: 等角色（role），类似 Java 的 @param、@return：

def connect(host, port, timeout=30):
    """
    建立到服务器的连接。
    
    详细描述可以写在这里，支持多行。
    
    :param host: 服务器地址（IP 或域名）
    :type host: str
    :param port: 端口号
    :type port: int
    :param timeout: 连接超时时间（秒），默认为30
    :type timeout: int, optional
    :return: 连接对象
    :rtype: Connection
    :raises ConnectionError: 当网络不可用时抛出
    :raises ValueError: 当端口不合法时抛出
    .. note:: 这是一个注意提示（类似 Javadoc 的 @note）
    .. seealso:: :func:`disconnect`
    """
    pass

风格 2：Google Style（现代推荐）

使用清晰的分块标题，可读性更强，适合没有 Sphinx 渲染的纯文本查看：

def connect(host, port, timeout=30):
    """
    建立到服务器的连接。
    
    Args:
        host (str): 服务器地址（IP 或域名）
        port (int): 端口号
        timeout (int, optional): 连接超时时间（秒）. Defaults to 30.
    
    Returns:
        Connection: 连接对象
    
    Raises:
        ConnectionError: 当网络不可用时抛出
        ValueError: 当端口不合法时抛出
    
    Note:
        这是一个注意提示
    """
    pass

风格 3：NumPy/SciPy Style（科学计算领域）

适合参数极多的复杂函数：

def connect(host, port, timeout=30):
    """
    建立到服务器的连接。
    
    Parameters
    ----------
    host : str
        服务器地址（IP 或域名）
    port : int
        端口号
    timeout : int, optional
        连接超时时间（秒），默认值为 30
    
    Returns
    -------
    Connection
        连接对象
    
    Raises
    ------
    ConnectionError
        当网络不可用时抛出
    """
    pass

三、Sphinx 支持配置

Sphinx 原生支持 reStructuredText，通过 Napoleon 扩展支持 Google 和 NumPy 风格：

# conf.py
extensions = [
    'sphinx.ext.napoleon',  # 支持 Google 和 NumPy 风格
    'sphinx.ext.autodoc',   # 自动从 docstring 提取文档
]

# 可选配置
napoleon_google_docstring = True   # 启用 Google 风格
napoleon_numpy_docstring = True    # 启用 NumPy 风格（默认 True）
napoleon_include_init_with_doc = True  # 包含 __init__ 文档

四、现代推荐：结合类型提示

Python 3.5+ 支持类型提示后，文档可以简化，因为参数类型已在签名中声明：

from typing import Optional

def connect(host: str, port: int, timeout: Optional[int] = 30) -> "Connection":
    """
    建立到服务器的连接。
    
    Args:
        host: 服务器地址（IP 或域名）
        port: 端口号
        timeout: 连接超时时间（秒），默认为30
    
    Returns:
        连接对象
    
    Raises:
        ConnectionError: 当网络不可用时
    """
    pass

类型信息在签名中，文档中无需重复 :type: 或 (str)，工具能自动提取。

五、类与模块文档

模块级文档

"""
my_module.py
提供数据处理功能。

示例:
    >>> import my_module
    >>> my_module.process([1, 2, 3])
"""

def process(data):
    """处理数据"""
    pass

# 运行时访问
import my_module
print(my_module.__doc__)  # 显示模块级文档

类文档

class ConnectionPool:
    """
    连接池管理类。
    
    类级别的详细描述...
    
    Attributes:
        max_size (int): 最大连接数
        current_size (int): 当前连接数
    
    Example:
        >>> pool = ConnectionPool(max_size=10)
        >>> conn = pool.get_connection()
    """
    
    def __init__(self, max_size=10):
        """
        初始化连接池。
        
        :param max_size: 最大连接数
        """
        self.max_size = max_size

六、风格选择建议

风格	推荐场景	配置难度
Sphinx/reST	官方库、大型框架（如 Django、Flask）	中（语法较繁琐）
Google Style	现代项目、团队协作（推荐）	低（可读性强）
NumPy Style	科学计算、AI 项目	低

建议：从 JavaDoc 迁移，Google Style 最友好（类似块标签），且配合 Type Hints 可以省略类型声明。

📌 本文是 python-basics 的专题展开。