📝 docs(typescript): 优化代码注释和类型声明

littleCareless · littleCareless · commit 35cbe8823a0e · 2025-01-22T10:21:10.000+08:00
-【代码质量】完善多个核心模块的文档注释
-【代码结构】重构并规范化配置和常量定义
-【代码组织】优化 WeeklyReportPanel 类的注释和方法说明
-【代码维护】增加配置键和接口的详细类型声明
diff --git a/src/config/generated/configKeys.ts b/src/config/generated/configKeys.ts
@@ -28,5 +28,8 @@ export const CONFIG_KEYS = {
   "FEATURES_COMMITFORMAT_ENABLEMERGECOMMIT": "dish-ai-commit.features.commitFormat.enableMergeCommit",
   "FEATURES_COMMITFORMAT_ENABLEEMOJI": "dish-ai-commit.features.commitFormat.enableEmoji",
   "FEATURES_WEEKLYREPORT": "dish-ai-commit.features.weeklyReport",
-  "FEATURES_WEEKLYREPORT_SYSTEMPROMPT": "dish-ai-commit.features.weeklyReport.systemPrompt"
+  "FEATURES_WEEKLYREPORT_SYSTEMPROMPT": "dish-ai-commit.features.weeklyReport.systemPrompt",
+  "FEATURES_CODEREVIEW": "dish-ai-commit.features.codeReview",
+  "FEATURES_CODEREVIEW_ENABLED": "dish-ai-commit.features.codeReview.enabled",
+  "FEATURES_CODEREVIEW_SYSTEMPROMPT": "dish-ai-commit.features.codeReview.systemPrompt"
 } as const;
diff --git a/src/constants.ts b/src/constants.ts
@@ -1,20 +1,37 @@
 import * as packageJson from "../package.json";
 
+/** 扩展的包名 */
 export const EXTENSION_NAME = packageJson.name;
+
+/** 扩展的显示名称 */
 export const DISPLAY_NAME = packageJson.displayName;
 
-// 使用命名空间组织命令
+/** 
+ * 使用命名空间组织的命令常量
+ * @namespace
+ */
 export const COMMANDS = {
+  /** Commit相关命令 */
   COMMIT: {
+    /** 生成commit信息的命令 */
     GENERATE: packageJson.contributes.commands[0].command,
   },
+  /** 模型相关命令 */
   MODEL: {
+    /** 显示模型选择的命令 */
     SHOW: packageJson.contributes.commands[1].command,
   },
+  /** 周报相关命令 */
   WEEKLY_REPORT: {
+    /** 生成周报的命令 */
     GENERATE: packageJson.contributes.commands[2].command,
   },
+  /** 代码审查相关命令 */
+  CODE_REVIEW: {
+    /** 执行代码审查的命令 */
+    REVIEW: packageJson.contributes.commands[3].command,
+  },
 } as const;
 
-// 添加类型导出
+/** COMMANDS常量的TypeScript类型 */
 export type CommandType = typeof COMMANDS;
diff --git a/src/extension.ts b/src/extension.ts
@@ -7,31 +7,39 @@ import { LocalizationManager } from "./utils/LocalizationManager";
 import { NotificationHandler } from "./utils/NotificationHandler";
 import { WeeklyReportPanel } from "./webview/WeeklyReportPanel";
 
-// This method is called when your extension is activated
-// Your extension is activated the very first time the command is executed
+/**
+ * 在首次执行命令时激活扩展
+ * @param {vscode.ExtensionContext} context - VS Code扩展上下文对象
+ * @throws {Error} 如果扩展激活失败将抛出错误
+ */
 export function activate(context: vscode.ExtensionContext) {
   try {
+    // 日志输出表示扩展已激活
     console.log('Extension "dish-ai-commit-gen" is now active!');
 
-    // 初始化本地化管理器（移除重复的初始化）
+    // 初始化本地化管理器
     LocalizationManager.initialize(context);
 
-    // 初始化配置管理器并添加到订阅列表
+    // 初始化配置管理器并注册到生命周期
     context.subscriptions.push(ConfigurationManager.getInstance());
+    
     console.log("注册命令");
-    // 注册所有命令
+    // 注册所有命令到VS Code
     registerCommands(context);
   } catch (e) {
     console.error("Error activating extension:", e);
-    // 添加用户可见的错误提示
+    // 向用户显示本地化的错误提示
     NotificationHandler.error(
       "extension.activation.failed",
       3000,
       e instanceof Error ? e.message : String(e)
     );
-    throw e;
+    throw e; // 重新抛出以便VS Code处理
   }
 }
 
-// This method is called when your extension is deactivated
+/**
+ * VS Code停用扩展时调用此方法
+ * 目前无需清理操作
+ */
 export function deactivate() {}
diff --git a/src/scripts/updateConfig.ts b/src/scripts/updateConfig.ts
@@ -1,3 +1,8 @@
+/**
+ * 配置更新脚本模块
+ * @module updateConfig
+ */
+
 import * as fs from "fs";
 import * as path from "path";
 import {
@@ -7,10 +12,21 @@ import {
   generateConfigKeys,
 } from "../config/ConfigSchema";
 
+/**
+ * 更新所有配置文件
+ * 包括更新 package.json 中的配置属性和生成配置键常量文件
+ * @returns {Promise<void>} 更新完成的 Promise
+ * @throws {Error} 如果配置更新过程中发生错误
+ */
 async function updateAllConfigs() {
+  /** 扩展名称常量 */
   const EXTENSION_NAME = "dish-ai-commit";
 
-  // 更新 package.json
+  /**
+   * 更新 package.json 中的配置属性
+   * @returns {Promise<void>} 更新完成的 Promise
+   * @throws {Error} 如果文件读写过程中发生错误
+   */
   async function updatePackageJson() {
     const packagePath = path.join(process.cwd(), "package.json");
     const pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
@@ -25,20 +41,26 @@ async function updateAllConfigs() {
     pkg.contributes.configuration.properties = {};
     const properties = pkg.contributes.configuration.properties;
 
-    // 递归遍历 CONFIG_SCHEMA 生成配置
+    /**
+     * 递归遍历配置模式对象,生成 VSCode 配置属性
+     * @param {ConfigObject} obj - 配置对象
+     * @param {string} [currentPath=""] - 当前配置路径
+     */
     function traverse(obj: ConfigObject, currentPath: string = "") {
       for (const [key, value] of Object.entries(obj)) {
+        // 构建完整的配置键路径
         const fullPath = currentPath ? `${currentPath}.${key}` : key;
         const configKey = `${EXTENSION_NAME}.${fullPath}`;
 
         if (isConfigValue(value)) {
+          // 构建基础配置属性对象
           const configProperty: Record<string, any> = {
             type: value.type,
             default: value.default,
             description: value.description,
           };
 
-          // 只有字符串类型的配置才可能有枚举值和枚举描述
+          // 处理字符串类型特有的枚举配置
           if (value.type === "string") {
             if ("enum" in value) {
               configProperty.enum = value.enum;
@@ -48,13 +70,14 @@ async function updateAllConfigs() {
             }
           }
 
-          // 添加作用域设置
+          // 添加配置作用域
           if ("scope" in value) {
             configProperty.scope = value.scope;
           }
 
           properties[configKey] = configProperty;
         } else if (typeof value === "object") {
+          // 递归处理嵌套对象
           traverse(value as ConfigObject, fullPath);
         }
       }
@@ -65,8 +88,14 @@ async function updateAllConfigs() {
     console.log("✅ package.json updated successfully");
   }
 
-  // 更新配置键常量
+  /**
+   * 更新配置键常量文件
+   * 生成 TypeScript 常量定义文件
+   * @returns {Promise<void>} 更新完成的 Promise
+   * @throws {Error} 如果文件写入失败
+   */
   async function updateConfigKeys() {
+    // 生成配置键对象
     const keys = generateConfigKeys(CONFIG_SCHEMA);
     const content = `// This file is auto-generated, do not edit manually
 export const CONFIG_KEYS = ${JSON.stringify(keys, null, 2)} as const;
@@ -76,7 +105,7 @@ export const CONFIG_KEYS = ${JSON.stringify(keys, null, 2)} as const;
       "src/config/generated/configKeys.ts"
     );
 
-    // 确保目录存在
+    // 确保目标目录存在
     const dir = path.dirname(configKeysPath);
     if (!fs.existsSync(dir)) {
       fs.mkdirSync(dir, { recursive: true });
@@ -87,6 +116,7 @@ export const CONFIG_KEYS = ${JSON.stringify(keys, null, 2)} as const;
   }
 
   try {
+    // 并行执行两个更新任务
     await Promise.all([updatePackageJson(), updateConfigKeys()]);
 
     console.log("🎉 All configurations updated successfully!");
diff --git a/src/types/weeklyReport.ts b/src/types/weeklyReport.ts
@@ -1,25 +1,55 @@
+/**
+ * 周报配置接口
+ * @interface Config
+ */
 export interface Config {
+    /** 总工作时长(小时) */
     totalHours: number;
+    /** 总工作天数 */
     totalDays: number;
+    /** 最小计算单位(小时) */
     minUnit: number;
 }
 
+/**
+ * Jira问题接口
+ * @interface JiraIssue
+ */
 export interface JiraIssue {
+    /** Jira问题的唯一标识符 */
     key: string;
+    /** 问题标题 */
     title: string;
+    /** 关联用户列表 */
     linkUsers?: string[];
+    /** 优先级 */
     priority?: string;
+    /** 问题描述 */
     description?: string;
 }
 
+/**
+ * 工作项接口
+ * @interface WorkItem
+ */
 export interface WorkItem {
+    /** 工作内容 */
     content: string;
+    /** 工作耗时 */
     time: string;
+    /** 工作描述 */
     description: string;
 }
 
+/**
+ * 代码仓库接口
+ * @interface Repository 
+ */
 export interface Repository {
+    /** 仓库类型: git或svn */
     type: 'git' | 'svn';
+    /** 仓库路径 */
     path: string;
+    /** 仓库作者 */
     author?: string;
 }
diff --git a/src/webview/WeeklyReportPanel.ts b/src/webview/WeeklyReportPanel.ts
