AI帮你写文档:API文档、README、注释,一键生成不用手写

大部分程序员讨厌写文档。不是懒——是写完代码已经很累了，还要用另一种语言解释一遍做了什么，这感觉像罚抄作业。AI恰好擅长这件事：读代码，解释代码。

五种文档，AI五分钟搞定

一、函数级注释

最基础的。选中一个函数，一句话就够了：

给以下函数添加 docstring，Google风格，包含：
- 功能描述
- Args（参数说明）
- Returns（返回值说明）
- Raises（可能抛出的异常）

```python
[粘贴你的函数]

AI会输出：

```python
def validate_email(email: str) -> bool:
    """验证邮箱地址格式是否有效。

    Args:
        email: 待验证的邮箱地址字符串。

    Returns:
        True 如果邮箱格式有效，否则 False。空字符串返回 False。

    Raises:
        TypeError: 当输入不是字符串类型时。
    """
    if not isinstance(email, str):
        raise TypeError("email must be a string")
    if not email:
        return False
    pattern = r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"
    return bool(re.match(pattern, email))

二、README.md

对于一个GitHub仓库：

请基于项目代码生成 README.md，结构：
- 项目名称和一句话简介
- 功能特性列表（从代码中推断）
- 快速开始（装机、配置、运行）
- API概览（如果项目有API）
- 技术栈
- 目录结构说明

只根据代码实际内容写，不要凭空编造功能。

关键约束： "只根据代码实际内容写"——防止AI脑补不存在的功能。

三、API文档

如果你用 FastAPI / Flask 写好了路由，让AI自动提取：

扫描 routes/ 目录下的所有路由文件，生成API文档：

| 方法 | 路径 | 功能 | 请求参数 | 返回值 |
|------|------|------|---------|--------|
| GET | /api/users | 获取用户列表 | ?page=&per_page= | {data, total} |
| POST | /api/users | 创建用户 | {name, email} | {id, name, email} |
...

请从代码中准确提取，不确定的字段标注"?"

四、Changelog

基于git log生成：

基于以下git log，生成CHANGELOG.md：
[贴 git log --oneline --since="2 weeks ago"]

按以下分类：
- 🚀 新功能
- 🐛 Bug修复
- 🔧 优化
- 📝 文档

五、架构决策记录（ADR）

对重要的技术决策：

我们为什么选择 PostgreSQL 而不是 MongoDB 做用户数据存储？
请从我们的代码结构和实际使用场景出发，生成一份架构决策记录：
- 背景
- 决策内容
- 考虑的备选方案
- 选择PostgreSQL的原因
- 带来的影响

文档的存放位置

不同类型的文档放在不同地方：

避免文档腐化

文档最大的问题不是写不出来，是写了不维护。AI能帮你写，但需要你建立更新机制。

在CI里加文档检查：

一个简单的GitHub Action：

- name: Check API docs
  run: |
    # 如果路由文件变了但API文档没变，警告
    if git diff --name-only HEAD~1 | grep "routes/" && 
       ! git diff --name-only HEAD~1 | grep "docs/api.md"; then
      echo "⚠️ API routes changed but docs/api.md not updated"
    fi

一个真实效率对比

我自己维护的一个中型项目（30+ API端点）：

而且AI写的英文文档质量通常比程序员好——措辞规范、语法正确、结构清晰。很多开源项目维护者已经用AI写初版文档，人只做终审。

文档有了，代码也写了，下一篇讲性能优化——用AI找到真正的瓶颈，不是盲猜然后瞎改。