CodeBuddy 能够自动为 Python 和 Ja vaScript 项目生成符合 PEP 257 或 JSDoc 标准的结构化注释，支持四种方式：函数级一键生成、多文件批量补全、局部代码解释以及自然语言反向生成。整个过程不会修改原有代码。

对于正在维护一个已有大量无注释的 Python 或 Ja vaScript 项目的开发者来说，手动补全函数级、类级甚至整个文件的规范注释，不仅耗时，还容易遗漏关键逻辑。CodeBuddy 能够基于语义理解，自动插入符合 PEP 257 或 JSDoc 标准的结构化注释，而且不改动任何一行原有代码。

函数级一键生成文档字符串

这一步适合刚写完但还没加注释的单个函数。AI 会读取参数名、返回值类型和函数体逻辑，自动生成带 :param、:return、:raises 等字段的 docstring。

1. 在编辑器中将光标置于目标函数名所在行，或用鼠标完整选中该函数（含 def/function 关键字、参数列表与缩进后的第一行代码）。

2. 右键 → 选择【Generate Doc】选项。

3. 等待 2–5 秒，AI 完成分析后，标准文档字符串会直接插入到函数顶部，格式为三重双引号包裹的多行字符串。

需要注意：如果函数内含复杂条件分支或调用外部服务，AI 可能无法准确推断所有异常路径，此时需要人工补充 :raises 说明。

批量为多个文件补全注释

当项目里有十几个 .py 或 .js 文件长期缺乏注释，逐个处理效率极低。此方法可一次性扫描并为所有可文档化对象注入基础注释块。

方法一：资源管理器多选触发

① 在 VS Code 资源管理器中按住 Ctrl 键，点击选中需补注释的全部源码文件（如 user_service.py、order_controller.js、utils.ts）。

② 右键 → 选择【Add Documentation to Selected Files】。

③ 系统会逐文件解析，只为函数、类、模块级对象添加注释，跳过变量、常量和纯表达式语句。

方法二：Craft 对话框指令驱动

在 Craft 界面输入指令：/add-docs --files src/api/ --style jsdoc --include-private，回车执行。该命令会递归扫描 src/api/ 目录下所有 .js/.ts 文件，强制为带 _ 前缀的私有方法也生成注释。

【必须确保项目根目录下存在 package.json 或 pyproject.toml，否则 CodeBuddy 无法识别语言生态与依赖上下文】

圈选局部代码生成解释型注释

适用于临时调试、交接代码或阅读他人写的晦涩逻辑块，比如一段嵌套 map+reduce+filter 的链式调用，或一个状态机转换的核心 switch 分支。

1. 用鼠标拖选目标代码段（最小粒度支持单行表达式，最大支持整个 class 定义）。

2. 右键 → 【腾讯云代码助手 > 解释代码】。

3. 模型返回解释后，点击“插入为注释”按钮，注释将以 // 或 /* */ 形式紧贴选中代码上方插入。

操作很简单，拖选目标代码区域，右键操作即可。但要注意：如果选中区域包含语法错误（如括号不匹配、缺少分号），AI 可能拒绝解析并报错，此时需要先修复基础语法再尝试。

用自然语言描述反向生成精准注释

当函数命名模糊（如 handleData()）、参数含义不直观（如 flag: boolean）、或业务逻辑超出代码字面量所能体现的范围时，该方式能让 AI 优先遵循你的中文意图，而非仅依赖符号推断。

第一步：将光标置于待注释函数内部任意位置（不必选中）。

第二步：按下快捷键 Ctrl+Shift+D（Windows/Linux）或 Cmd+Shift+D（macOS）。

第三步：在弹出框中用中文写清楚真实用途，例如：“根据用户设备指纹和 IP 地址判断是否为高风险登录，命中规则时返回 {riskLevel: 'high', reason: '异地频繁切换'}”。

第四步：点击生成，AI 会覆盖默认推断结果，输出完全匹配你描述的注释内容，并自动适配当前语言的注释风格。

关键在于描述必须包含输入来源、判断依据、输出结构三个要素，缺一不可，否则生成的注释仍会偏向代码字面量。