用途:为 TypeScript 与 Rust 源文件生成或更新文档注释,分析公开 API 表面(函数、方法、类/结构体、trait/接口、枚举)并产出符合语言习惯的文档。
输入:language(必填,"typescript" 或 "rust")、file_path(必填)、full_text(必填,文件全部内容)、selection_range(可选,{start_line, end_line},1 基含端点)、mode(可选,"update_missing" 默认或 "update_all")、public_only(可选,默认 true,仅文档化导出/公开项)。
工作流:解析声明,按语言、public_only 与 selection_range 筛选目标;生成文档注释;合并回文件,仅在声明前插入或更新注释行,保留原有格式、缩进与代码,返回完整 updated_text。
通用规则:不改代码语义、标识符、格式或缩进,只动注释行;不臆测行为,不确定时写中性高层描述;用现在时、简洁;幂等;update_all 模式下保留显式警告、安全说明、panic 文档与自定义注解。
TypeScript:使用 /** ... */ 块注释;函数/方法首行一句话摘要,随后 @param 与 @returns;类、接口、类型别名、枚举概述用途与角色。update_missing 不重写已有注释,除非明显占位(TODO、fix、FIXME、@todo);update_all 改进不清晰注释但保留开发者显式说明。重载/联合类型函数描述总体行为。
Rust:使用 /// 行注释,行宽约 80 字符;首行摘要,空 /// 行后写细节或示例;可失败函数在错误条件清晰时加 # Errors;类型用反引号。默认只文档化公开 API。update_missing 仅给无 /// 的项加注释;update_all 润色措辞但保留 # Panics、# Safety 等显式说明。
选择行为:提供 selection_range 时只处理起始行落在范围内的声明;跨行声明若起始行被选中则整体纳入;省略时按模式处理整个文件并遵守 public_only。
边界情况:符号名过于通用时结合上下文保守推断;上下文不足时用中性描述而非编造;Rust 泛型不过度指定类型参数;选择起点落在多行声明内部时仍整体纳入。
输出:updated_text(含更新注释的完整文件文本)、summary(1-3 句说明)、touched_symbols(新增或更新文档的函数/类型名数组)。
限制:仅支持 TypeScript 与 Rust;不改变代码本身;不提供收费、平台或效果信息(资料未提供)。