pdoc项目中装饰器修改文档字符串的注意事项

在Python开发中，我们经常使用装饰器来扩展函数功能。当使用pdoc这类文档生成工具时，开发者可能会遇到装饰器修改文档字符串不生效的情况。本文将深入分析这一现象的原因，并提供解决方案。

问题现象

开发者尝试通过装饰器向函数添加额外的文档信息，例如：

def expand(text: str, /):
    def decorator(f):
        @functools.wraps(f)
        def wrapper(*args, **kwargs):
            return f(*args, **kwargs)
        
        # 尝试修改wrapper的__doc__
        wrapper.__doc__ = "额外信息\n" + (f.__doc__ or "")
        return wrapper
    return decorator

虽然在运行时print(func.__doc__)能正确显示修改后的文档，但使用pdoc生成的文档却未包含这些修改。

原因分析

pdoc在设计上有一个特殊行为：当检测到函数被装饰器包装时，它会直接获取原始函数（而非包装后的函数）的文档字符串。这种设计主要是为了避免以下情况：

1. 许多标准库和第三方装饰器会自带文档字符串
2. 装饰器的文档可能会掩盖原始函数的文档
3. 保持文档生成的一致性

解决方案

要确保装饰器修改的文档能被pdoc识别，应该直接修改原始函数的__doc__属性，而不是包装函数的：

def expand(text: str, /):
    def decorator(f):
        @functools.wraps(f)
        def wrapper(*args, **kwargs):
            return f(*args, **kwargs)
        
        # 直接修改原始函数的__doc__
        f.__doc__ = "额外信息\n" + (f.__doc__ or "")
        return wrapper
    return decorator

最佳实践

1. 保持一致性：无论是否使用pdoc，直接修改原始函数的文档字符串都是更可靠的做法
2. 文档清理：使用inspect.cleandoc处理文档字符串可以避免格式问题
3. 兼容性考虑：如果装饰器需要在运行时和文档生成时都生效，应该同时考虑两种场景

总结

理解pdoc的这种特殊行为对于生成准确的API文档非常重要。通过直接修改原始函数的文档字符串，可以确保文档生成工具和运行时行为的一致性。这种模式也符合Python装饰器的最佳实践，即在不改变原始函数签名和属性的前提下扩展功能。

记住，良好的文档实践应该同时考虑人工阅读和工具生成的场景，确保代码的文档在各种环境下都能正确呈现。