文档生成：代码即文档

文档生成从源码的函数签名、类型标注与注释抽取信息，自动产出 API 文档、README 与使用示例，缓解「代码改了文档没改」的问题。它让文档与代码同源。

它是什么

工具（如借助 docstring 的 Sphinx、基于模型的说明生成）读取代码与注释，输出可读文档。它能把参数、返回值、异常整理成表格，并生成上手示例。

为什么值得

• 文档与代码同源，减少脱节与过期。
• 为新成员快速生成上手指南与示例，降低沟通成本。
• 把写文档的成本从负担转为一次生成与定期刷新。
• 让内部函数契约显性化，便于复用。

怎么生成

先写好 docstring，再让模型扩写成章节化说明，保证表述与实现一致。

def send_email(to: str, subject: str, body: str) -> bool:
    """发送邮件。

    Args:
        to: 收件人地址。
        subject: 主题。
        body: 正文。
    Returns:
        是否发送成功。
    """

注意点

• 模型可能把「函数看起来做什么」写成事实，需核对真实行为。

• 公开的 API 文档不要泄露内部实现细节与敏感字段。

• 自动文档要随代码评审一起更新，避免漂移。

• 以 docstring 为准，生成只是呈现，不要反向信任生成物。

• 对公开 SDK 优先生成使用示例，比纯参数表更易上手。

• 把文档构建接入 CI，防止 docstring 缺失导致空白页面。

• 对常变动的接口，用脚本定期刷新文档，避免长期失修。

小结

文档生成从源码与注释产出可读说明，降低文档脱节与维护成本；但生成内容须核对真实行为，并纳入评审随代码同步更新，以 docstring 为权威来源。

参考与延伸阅读

• Sphinx 官方文档（Python 文档生成）。已核验。https://www.sphinx-doc.org/en/master/
• Google Python 风格指南（docstring 约定）。已核验。https://google.github.io/styleguide/pyguide.html