python __doc__

在Python中，__doc__ 是一个特殊的内置属性，用于存储模块、类、函数或方法的文档字符串（docstring）。文档字符串是对代码功能的描述，通常位于模块、类或函数的第一行，可以通过 对象.__doc__ 动态访问。

1. 文档字符串的定义方式

文档字符串用三引号（单引号或双引号）包裹，位于代码对象的开头：

模块级文档字符串

"""这是一个示例模块，提供数学计算功能。"""

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

类级文档字符串

class Calculator:
    """一个简单的计算器类，支持基本数学运算。"""
    
    def add(self, a, b):
        """计算并返回两个数的和。
        
        参数:
            a (int/float): 第一个操作数
            b (int/float): 第二个操作数
            
        返回:
            int/float: 两数之和
        """
        return a + b

2. __doc__ 属性的作用

• 交互式帮助：在REPL中使用 help(对象) 时，会显示 __doc__ 的内容。
• 自动生成文档：如Sphinx、Doxygen等工具会提取 __doc__ 生成API文档。
• 代码自省：运行时动态获取代码对象的说明。

示例：访问文档字符串

def multiply(a, b):
    """返回两个数的乘积。"""
    return a * b

print(multiply.__doc__)  # 输出: "返回两个数的乘积。"

3. __doc__ 的特殊用法

动态修改文档字符串

虽然不常见，但可以在运行时修改 __doc__：

def greet(name):
    return f"Hello, {name}!"

greet.__doc__ = "向指定的人打招呼并返回问候语。"
print(greet.__doc__)  # 输出: "向指定的人打招呼并返回问候语。"

模块级文档字符串的快捷方式

在模块文件的第一行使用 __doc__ = "..." 可以直接定义模块文档：

__doc__ = """这是一个示例模块，提供数学计算功能。"""

def subtract(a, b):
    return a - b

4. 文档字符串的规范

推荐遵循 PEP 257 的规范：

• 单行文档：简洁描述功能，不使用空行。
• 多行文档：第一行概述，空行后详细描述，可包含参数、返回值、异常等说明。

推荐格式（Google风格）

def divide(a, b):
    """计算两个数的商。
    
    Args:
        a (int/float): 被除数
        b (int/float): 除数（不能为0）
        
    Returns:
        float: 商
        
    Raises:
        ZeroDivisionError: 如果b为0
    """
    if b == 0:
        raise ZeroDivisionError("除数不能为0")
    return a / b

5. 与其他语言的对比

• Java：使用 /** ... */ 注释和Javadoc工具。
• C++：使用Doxygen风格的 /// 或 /** ... */ 注释。
• Python：直接将文档作为字符串存储在 __doc__ 属性中，无需额外工具即可访问。

总结

__doc__ 是Python中存储文档字符串的特殊属性，它让代码的自描述性更强，并支持动态生成帮助信息。合理使用文档字符串是编写高质量Python代码的重要实践。