gendoc
Generate detailed JSDoc/TSDoc comments for code to improve documentation and maintainability. Supports multiple comment styles and languages.
Instructions
【生成注释】为代码生成详细的 JSDoc/TSDoc 注释
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | 需要生成注释的代码 | |
| style | No | 注释风格：jsdoc, tsdoc, javadoc（默认 jsdoc） | |
| lang | No | 语言：zh, en（默认 zh） |
Implementation Reference
- src/tools/gendoc.ts:2-210 (handler)The core handler function for the 'gendoc' tool. It constructs a comprehensive prompt message including code, style, language preferences, detailed templates for JSDoc/TSDoc comments, guidelines, and quality standards, then returns it as MCP content for LLM processing.export async function gendoc(args: any) { try { const code = args?.code || ""; const style = args?.style || "jsdoc"; // jsdoc, tsdoc, javadoc const lang = args?.lang || "zh"; // zh, en const message = `请为以下代码生成详细的注释文档： 📝 **代码内容**： ${code || "请提供需要生成注释的代码"} 📖 **注释风格**：${style} 🌐 **语言**：${lang === "zh" ? "中文" : "English"} --- ## 注释生成指南 ### JSDoc/TSDoc 格式 **函数注释模板**： \`\`\`typescript /** * 函数简短描述（一句话） * * 详细描述功能、用途、使用场景（可选，多行） * * @param {类型} 参数名 - 参数描述 * @param {类型} 参数名 - 参数描述 * @returns {类型} 返回值描述 * @throws {ErrorType} 抛出异常的情况 * * @example * // 使用示例 * const result = functionName(arg1, arg2); * console.log(result); // 输出: ... * * @see 相关函数或文档链接 * @since 1.0.0 * @deprecated 使用 newFunction 替代（如果已废弃） */ function functionName(param1, param2) { // ... } \`\`\` **类注释模板**： \`\`\`typescript /** * 类简短描述 * * 详细描述类的职责、使用场景 * * @class * @example * const instance = new ClassName(param); * instance.method(); */ class ClassName { /** * 构造函数描述 * @param {类型} param - 参数描述 */ constructor(param) {} /** * 方法描述 * @returns {类型} 返回值描述 */ method() {} } \`\`\` **接口注释模板**： \`\`\`typescript /** * 接口描述 * * @interface */ interface InterfaceName { /** 属性描述 */ property: string; /** * 方法描述 * @param {类型} param - 参数描述 * @returns {类型} 返回值描述 */ method(param: string): void; } \`\`\` **类型注释模板**： \`\`\`typescript /** * 类型描述 * * @typedef {Object} TypeName * @property {string} prop1 - 属性 1 描述 * @property {number} prop2 - 属性 2 描述 */ type TypeName = { prop1: string; prop2: number; }; \`\`\` --- ## 注释内容要求 ### 必须包含 1. **功能描述** - 简短说明（一句话） - 详细说明（用途、场景、原理） 2. **参数说明** - 参数类型 - 参数含义 - 是否可选 - 默认值（如有） - 取值范围/约束（如有） 3. **返回值** - 返回类型 - 返回值含义 - 可能的返回值 4. **异常情况** - 可能抛出的异常 - 抛出条件 5. **使用示例** - 基本用法 - 典型场景 - 边界情况 ### 可选包含 1. **复杂度**：\`@complexity O(n)\` 2. **版本信息**：\`@since 1.0.0\` 3. **作者**：\`@author Kyle\` 4. **废弃信息**：\`@deprecated\` 5. **相关链接**：\`@see\` 6. **待办事项**：\`@todo\` --- ## 注释质量标准 **好的注释**： - ✅ 说明"为什么"，而不只是"做什么" - ✅ 描述边界条件和特殊情况 - ✅ 提供有意义的示例 - ✅ 保持与代码同步 - ✅ 使用清晰简洁的语言 **避免的注释**： - ❌ 重复代码内容的注释 - ❌ 过时的注释 - ❌ 误导性的注释 - ❌ 废话注释（如：\`// 定义变量 x\`） --- ## 特殊注释标记 **标记类型**： \`\`\`typescript // TODO: 待实现的功能 // FIXME: 需要修复的问题 // HACK: 临时解决方案 // NOTE: 重要说明 // WARNING: 警告信息 // OPTIMIZE: 可优化的地方 \`\`\` --- 现在请为代码生成${lang === "zh" ? "中文" : "英文"}的${style}风格注释文档，包括： 1. 完整的函数/类/接口注释 2. 复杂逻辑的行内注释 3. 使用示例 4. 特殊情况说明`; return { content: [ { type: "text", text: message, }, ], }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: "text", text: `❌ 生成注释失败: ${errorMessage}`, }, ], isError: true, }; } }
- src/index.ts:203-224 (schema)The input schema definition for the 'gendoc' tool registered in the ListTools handler, specifying parameters: code (string), style (string, default jsdoc), lang (string, default zh).{ name: "gendoc", description: "【生成注释】为代码生成详细的 JSDoc/TSDoc 注释", inputSchema: { type: "object", properties: { code: { type: "string", description: "需要生成注释的代码", }, style: { type: "string", description: "注释风格：jsdoc, tsdoc, javadoc（默认 jsdoc）", }, lang: { type: "string", description: "语言：zh, en（默认 zh）", }, }, required: [], }, },
- src/index.ts:489-490 (registration)Registration of the gendoc handler in the CallToolRequest switch statement, dispatching calls to the gendoc function.case "gendoc": return await gendoc(args);
- src/tools/index.ts:11-11 (registration)Re-export of the gendoc function from its implementation module, allowing import in src/index.ts.export { gendoc } from "./gendoc.js";
- src/index.ts:12-13 (registration)Import statement in src/index.ts that brings in the gendoc function from src/tools/index.js for use in the server handlers.detectShell, initSetting, initProject, gencommit, debug, genapi, codeReview, gentest, genpr, checkDeps, gendoc, genchangelog, refactor, perf,