gendoc

Instructions

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,