乐于分享
好东西不私藏

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

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的原因
- 带来的影响

文档的存放位置

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

文档类型 位置 什么时候更新
函数注释 代码里 改代码时顺手改
API文档 docs/api.md API有变化时
README 项目根目录 新增功能、改安装方式时
ADR docs/decisions/ 做重大技术决策时
Changelog CHANGELOG.md 发版时

避免文档腐化

文档最大的问题不是写不出来,是写了不维护。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辅助
给所有函数加 docstring 3小时 5分钟
写API文档 4小时 2分钟
补 README 1小时 1分钟
写部署文档 2小时 5分钟
总计 10小时 13分钟

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


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

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料