通义灵码的文档注释生成功能有着严格的触发要求，并非自动生效。很多开发者遭遇“功能置灰”或“无响应”时，通常并非模型能力不足，而是触发条件未满足。关键在于：插件必须已登录、光标需停放在正确位置、行尾不得残留注释、且选中完整的函数结构。任何一步未到位，AI便不会响应。

写完一个Python函数或Java方法后，如果光标停在错误位置、行尾注释未删除、插件也未登录，通义灵码自然不会响应。这并非模型能力不足，而是触发条件完全未满足。只有严格按照精确的操作路径，AI才会自动生成标准的docstring或Javadoc。

确保基础条件全面就位

打开VS Code或IntelliJ IDEA，进入插件市场搜索“通义灵码”并安装，重启编辑器，点击侧边栏的Lingma图标，使用阿里云账号扫码或密码登录。注意：未登录状态下，所有注释生成功能均为灰色，无法点击。

同时，确认当前文件是否为支持的语言（Python、Java、TypeScript、JS），并且项目已正确加载。若状态栏右下角没有Lingma图标或显示“未连接”，则说明上下文尚未就绪，任何操作均会无效。

Python函数生成Google风格文档注释的方法

这里提供几种便捷方式，任选其一即可。

方法一：快捷键一键插入
将光标精准停在函数定义行末尾冒号:之后、换行符之前。例如，对于def load_config(path: str) -> dict:，光标应紧贴冒号右侧，不可有空格或换行。随后按Ctrl+Shift+D（Windows/Linux）或Cmd+Shift+D（macOS），AI便会自动插入包含Args、Returns、Raises的三引号框架，并将光标定位在Args描述区。

方法二：手动输入触发词
在函数定义下方的空行输入Args:，然后按Tab键，AI会自动补全参数名和类型（依赖函数签名中的类型提示）。接着输入Returns:，再按Tab，即可补全返回值描述。若缺少类型注解，Returns行可能留空或输出‘None’。

方法三：三引号触发
将光标停在函数定义行末尾的冒号后，按Enter换行，然后立即按Tab，或直接输入"""，通义灵码便会在新行补全整个docstring框架。如果光标已在函数体第一行（如def foo():下方的空行），直接输入"""同样能触发，但成功率会下降约40%，因为模型容易被误判为普通字符串的开始。

Java方法生成Javadoc注释

Java的规则稍显严格，但操作并不复杂。

第一步：确认光标位置
光标必须置于方法签名正上方的空白行。不能在方法体内部、类声明行或注释块中，只能停留在public String getName() {这一行的正上方空行处。

第二步：输入/**并回车
通义灵码会立即生成带有@param、@return、@throws的标准Javadoc框架。若方法存在多次重载且参数名完全相同，AI可能混淆描述内容，此时需手动删除重复生成的@param行。

第三步：填写参数名并按Tab补全细节
例如输入userId，然后按Tab，AI会自动补全@param userId 用户唯一标识,长度6~18位字母数字组合。此步骤依赖参数名的语义推断，若变量名为缩写（如usr），可能被误识别为User，需要人工核对。

避免常见失败场景

一个常见的陷阱是：函数定义行末尾若存在像# xxx这样的行尾注释，通义灵码大概率无法生成docstring，因为AI会认为用户已主动添加说明，无需再补充。因此，必须删除行末的#注释，才能正常触发文档注释补全。

另外，在IDEA中，若只选中函数内部的某几行代码，生成的注释会变为对局部逻辑的解释，而非标准函数级文档注释。务必选中整个函数结构：从def或public开始，到闭合大括号}结束。

还有一点，VS Code不支持右键菜单直接“生成注释”，必须经由命令面板：按Ctrl+Shift+P，输入Lingma: Comment，然后回车执行。否则，将无法找到该功能入口。