refactor🎨: (阅读代码)：logging.ts增加注释

src/logging.ts

@@ -1,10 +1,22 @@
+// 导入 FileSystemConfig 类型和 isFileSystemConfig 函数，用于处理文件系统配置
 import { FileSystemConfig, isFileSystemConfig } from 'common/fileSystemConfig';
+// 导入 vscode 模块，用于访问 VS Code 的 API
 import * as vscode from 'vscode';
 
+
 // Since the Extension Development Host runs with debugger, we can use this to detect if we're debugging.
 // The only things it currently does is copying Logging messages to the console, while also enabling
 // the webview (Settings UI) from trying a local dev server first instead of the pre-built version.
+// 定义一个名为 DEBUG 的布尔类型的变量，初始值为 false
 export let DEBUG: boolean = false;
+
+/**
+ * 设置调试模式
+ * @param debug - 一个布尔值，指示是否启用调试模式
+ * @remarks
+ * 当设置为 true 时，会启用调试模式，并尝试安装一些调试工具。
+ * 如果设置为 false，则不会进行任何操作。
+ */
 export function setDebug(debug: boolean) {
   console.warn(`[vscode-sshfs] Debug mode set to ${debug}`);
   DEBUG = debug;
@@ -17,6 +29,7 @@ export function setDebug(debug: boolean) {
   }
 }
 
+// 创建一个名为 'SSH FS' 的输出通道，用于在 VS Code 中显示日志信息
 export const OUTPUT_CHANNEL = vscode.window.createOutputChannel('SSH FS');
 
 export interface LoggingOptions {
@@ -26,6 +39,12 @@ export interface LoggingOptions {
    * - `1`: Only report the name (or first line of stacktrace if missing)
    * - `2`: Report name and stacktrace (if available) (default for `WARNING`/`ERROR`)
    */
+  /**
+   * 报告日志记录器名称/堆栈跟踪的级别：
+   * - `0`：不报告任何内容（默认值为 `WARNING`/`ERROR`）
+   * - `1`：仅报告名称（如果缺少堆栈跟踪，则报告第一行）
+   * - `2`：报告名称和堆栈跟踪（如果可用）（默认值为 `WARNING`/`ERROR`）
+   */
   reportedFromLevel: number;
   /**
    * Whether to output a stacktrace of the .info() call etc
@@ -35,12 +54,25 @@ export interface LoggingOptions {
    * 
    * Defaults to `3` for `WARNING`, `5` for `ERROR` and `0` for everything else.
   */
+  /**
+   * 是否输出调用堆栈跟踪：
+   * - `0`：不输出堆栈跟踪
+   * - `-1`：输出整个堆栈跟踪
+   * - `N`：仅输出前 N 帧
+   * 
+   * 默认值为 `3`（`WARNING`），`5`（`ERROR`），其他级别为 `0`。
+  */
   callStacktrace: number;
   /**
    * Used with `.callStacktrace` to skip the given amount of stacktraces in the beginning.
    * Useful when `.info()` etc is called from a helper function which itself isn't worth logging the stacktrace of.
    * Defaults to `0` meaning no offset.
    */
+  /**
+   * 与 `.callStacktrace` 一起使用，用于在开始时跳过给定数量的堆栈跟踪。
+   * 当 `.info()` 等方法从一个辅助函数调用时，这个选项很有用，因为辅助函数本身不值得记录堆栈跟踪。
+   * 默认值为 `0`，表示没有偏移。
+  */
   callStacktraceOffset: number;
   /**
    * Used when the "message" to be logged is an Error object with a stack:
@@ -48,37 +80,93 @@ export interface LoggingOptions {
    * - `-1`: Output the whole stack
    * - `N`: Only output the first N lines
    */
+  /**
+   * 当要记录的“消息”是一个带有堆栈的 Error 对象时使用：
+   * - `0`：不输出堆栈（这是 `DEBUG` 和 `INFO` 的默认值）
+   * - `-1`：输出整个堆栈
+   * - `N`：仅输出前 N 行
+  */
   maxErrorStack: number;
 }
 
+// 定义了一个日志记录选项的常量，其中 callStacktrace 设置为 0，表示不输出堆栈跟踪信息。
 export const LOGGING_NO_STACKTRACE: Partial<LoggingOptions> = { callStacktrace: 0 };
+
+// 定义了一个日志记录选项的常量，其中 callStacktrace 设置为 1，表示只输出一行堆栈跟踪信息。
 export const LOGGING_SINGLE_LINE_STACKTRACE: Partial<LoggingOptions> = { callStacktrace: 1 };
 
+/**
+ * 检查错误对象是否包含 promiseCause 属性，该属性是一个错误对象，并且还有一个名为 promiseCauseName 的字符串属性
+ * @param error - 要检查的错误对象
+ * @returns 如果 error 对象包含 promiseCause 属性，则返回 true，否则返回 false
+ */
 function hasPromiseCause(error: Error): error is Error & { promiseCause: Error; promiseCauseName: string } {
   return 'promiseCause' in error && (error as any).promiseCause instanceof Error;
 }
 
+/**
+ * 定义了日志记录器的默认级别。
+ * 这些级别包括：
+ * - 'DEBUG'：用于调试信息。
+ * - 'INFO'：用于一般信息。
+ * - 'WARNING'：用于警告信息。
+ * - 'ERROR'：用于错误信息。
+ */
 export type LoggerDefaultLevels = 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR';
 
+/**
+ * 定义了一个特定类型的日志记录器的行为。
+ * 这个日志记录器具有以下属性和方法：
+ * - `logger`: 日志记录器的实例。
+ * - `type`: 日志记录的类型，是 `LoggerDefaultLevels` 联合类型的一个值。
+ * - `options`: 日志记录的选项，是 `LoggingOptions` 接口的一个部分。
+ * - `(error: Error, options?: Partial<LoggingOptions>): void`: 记录一个错误信息，可以指定额外的选项。
+ * - `(message: string, options?: Partial<LoggingOptions>): void`: 记录一个字符串信息，可以指定额外的选项。
+ * - `(template: TemplateStringsArray,...args: any[]): void`: 记录一个模板字符串信息，可以指定额外的选项。
+ * - `withOptions(options: Partial<LoggingOptions>): LoggerForType`: 返回一个新的 `LoggerForType` 实例，具有指定的选项。
+ */
 export interface LoggerForType {
+  // 日志记录器的实例
   logger: Logger;
+  // 日志记录的类型
   type: LoggerDefaultLevels;
+  // 日志记录的选项
   options: Partial<LoggingOptions>;
+  // 记录一个错误信息，可以指定额外的选项
   (error: Error, options?: Partial<LoggingOptions>): void;
+  // 记录一个字符串信息，可以指定额外的选项
   (message: string, options?: Partial<LoggingOptions>): void;
+  // 记录一个模板字符串信息，可以指定额外的选项
   (template: TemplateStringsArray, ...args: any[]): void;
+  // 返回一个新的 LoggerForType 实例，具有指定的选项
   withOptions(options: Partial<LoggingOptions>): LoggerForType;
 }
 
+/**
+ * Logger 类用于记录日志信息
+ */
  class Logger {
+  // 父 Logger 对象，用于在当前 Logger 无法处理日志时将其传递给父 Logger
   protected parent?: Logger;
+  // 堆栈跟踪信息，用于记录日志时提供更多的上下文信息
   protected stack?: string;
+  // 默认的日志记录选项
   protected defaultLoggingOptions: LoggingOptions = {
+    // 报告日志记录器名称/堆栈跟踪的级别
     reportedFromLevel: 0,
+    // 是否输出调用堆栈跟踪
     callStacktrace: 0,
+    // 在开始时跳过给定数量的堆栈跟踪
     callStacktraceOffset: 0,
+    // 当要记录的“消息”是一个带有堆栈的 Error 对象时使用
     maxErrorStack: 0,
   };
+
+  /**
+   * 构造函数，用于初始化 Logger 对象
+   * @param name - 日志记录器的名称
+   * @param generateStack - 是否生成堆栈跟踪信息
+   */
    protected constructor(protected name?: string, generateStack: number | boolean = false) {
     if (generateStack) {
       const len = typeof generateStack === 'number' ? generateStack : 1;
@@ -86,11 +174,18 @@ class Logger {
       this.stack = stack || '<stack unavailable>';
     }
   }
+
+  /**
+   * 打印日志信息
+   * @param type - 日志类型
+   * @param message - 日志信息
+   * @param options - 日志记录选项
+   */
    protected doPrint(type: string, message: string, options: LoggingOptions) {
     const { reportedFromLevel } = options;
-    // Calculate prefix
+    // 计算前缀
     const prefix = this.name? `[${this.name}] ` : '';
-    // Calculate suffix
+    // 计算后缀
     let suffix = '';
     if (this.name && this.stack && reportedFromLevel >= 2) {
       suffix = `\nReported by logger ${this.name}:\n${this.stack}`;
@@ -101,20 +196,27 @@ class Logger {
     } else if (this.stack && reportedFromLevel === 1) {
       suffix = `\nReported by logger:\n${this.stack.split('\n', 2)[0]}`;
     }
-    // If there is a parent logger, pass the message with prefix/suffix on
+    // 如果有父 Logger，则将带有前缀/后缀的消息传递给父 Logger
     if (this.parent) return this.parent.doPrint(type, `${prefix}${message}${suffix}`, options);
-    // There is no parent, we're responsible for actually logging the message
+    // 没有父 Logger，我们负责实际记录消息
     const space = ' '.repeat(Math.max(0, 8 - type.length));
     const msg = `[${type}]${space}${prefix}${message}${suffix}`
     OUTPUT_CHANNEL.appendLine(msg);
-    // VS Code issue where console.debug logs twice in the Debug Console
+    // VS Code 问题，console.debug 在调试控制台中记录两次
     if (type.toLowerCase() === 'debug') type = 'log';
     if (DEBUG) (console[type.toLowerCase()] || console.log).call(console, msg);
   }
+
+  /**
+   * 格式化值
+   * @param value - 要格式化的值
+   * @param options - 日志记录选项
+   * @returns 格式化后的字符串
+   */
    protected formatValue(value: any, options: LoggingOptions): string {
     if (typeof value === 'string') return value;
     if (value instanceof Error && value.stack) {
-      // Format errors with stacktraces to display the JSON and the stacktrace if needed
+      // 格式化带有堆栈跟踪的错误，以显示 JSON 和堆栈跟踪（如果需要）
       let result = `${value.name}: ${value.message}`;
       try {
         const json = JSON.stringify(value);
@@ -150,10 +252,17 @@ class Logger {
       }
     }
   }
+
+  /**
+     * 打印日志信息
+     * @param type - 日志类型
+     * @param message - 日志信息
+     * @param partialOptions - 日志记录选项
+     */
   protected print(type: string, message: string | Error, partialOptions?: Partial<LoggingOptions>) {
     const options: LoggingOptions = {...this.defaultLoggingOptions,...partialOptions };
     message = this.formatValue(message, options);
-    // Do we need to also output a stacktrace?
+    // 是否需要输出堆栈跟踪？
     const { callStacktrace, callStacktraceOffset = 0 } = options;
     if (callStacktrace) {
       let stack = new Error().stack;
@@ -162,66 +271,163 @@ class Logger {
       stack = split? split.join('\n') : '<stack unavailable>';
       message += `\nLogged at:\n${stack}`;
     }
-    // Start the (recursive parent-related) printing
+    // 开始（递归父相关）打印
     this.doPrint(type.toUpperCase(), message, options as LoggingOptions)
   }
+
+  /**
+   * 打印模板字符串日志信息
+   * @param type - 日志类型
+   * @param template - 模板字符串
+   * @param args - 模板字符串参数
+   * @param partialOptions - 日志记录选项
+   */
    protected printTemplate(type: string, template: TemplateStringsArray, args: any[], partialOptions?: Partial<LoggingOptions>) {
     const options: LoggingOptions = { ...this.defaultLoggingOptions, ...partialOptions };
     options.callStacktraceOffset = (options.callStacktraceOffset || 0) + 1;
     this.print(type, template.reduce((acc, part, i) => acc + part + (i < args.length ? this.formatValue(args[i], options) : ''), ''), partialOptions);
   }
+
+  /**
+   * 创建一个新的 Logger 对象，该对象是当前 Logger 的子 Logger
+   * @param name - 子 Logger 的名称
+   * @param generateStack - 是否生成堆栈跟踪信息
+   * @returns 新的 Logger 对象
+   */
    public scope(name?: string, generateStack: number | boolean = false) {
     const logger = new Logger(name, generateStack);
     logger.parent = this;
     return logger;
   }
+
+  /**
+   * 包装日志类型
+   * @param type - 日志类型
+   * @param options - 日志记录选项
+   * @returns 包装后的日志记录器
+   */
   public wrapType(type: LoggerDefaultLevels, options: Partial<LoggingOptions> = {}): LoggerForType {
+    /**
+     * 定义一个函数，它接受一个消息参数，可以是字符串、错误对象或模板字符串数组，并接受一个可选的部分日志记录选项参数
+     * 如果消息是字符串或错误对象，则调用 logger 的 print 方法记录日志
+     * 如果消息是模板字符串数组，则调用 logger 的 printTemplate 方法记录日志
+     * 如果消息既不是字符串也不是错误对象也不是模板字符串数组，则记录一个错误信息
+     * @param message - 要记录的消息，可以是字符串、错误对象或模板字符串数组
+     * @param args - 模板字符串数组的参数
+     * @param partialOptions - 部分日志记录选项
+     * @returns 返回记录的日志信息
+     */
     const result: LoggerForType = (message: string | Error | TemplateStringsArray, ...args: any[]) => {
+      /**
+       * 合并当前日志记录器的选项和传入的选项，生成一个新的选项对象
+       * 同时，将新的选项对象中的 callStacktraceOffset 属性值加 1
+       */
       const options = { ...result.options };
       options.callStacktraceOffset = (options.callStacktraceOffset || 0) + 1;
+      /**
+       * 根据传入的 message 参数类型，选择不同的日志记录方法
+       * 如果 message 是字符串或 Error 对象，则调用 print 方法记录日志
+       * 如果 message 是模板字符串数组，则调用 printTemplate 方法记录日志
+       * 如果 message 既不是字符串也不是 Error 对象也不是模板字符串数组，则记录一个错误信息
+       */
       if (typeof message === 'string' || message instanceof Error) {
         return result.logger.print(result.type, message, options)
       } else if (Array.isArray(message)) {
         return result.logger.printTemplate(result.type, message, args, options)
       }
+      // 记录错误信息
       result.logger.error`Trying to log type ${type} with message=${message} and args=${args}`;
     };
+
+    // 设置 result 对象的 logger 属性为当前 Logger 实例
     result.logger = this;
+    // 设置 result 对象的 type 属性为传入的 type 参数
     result.type = type;
+    // 设置 result 对象的 options 属性为传入的 options 参数
     result.options = options;
+    // 定义一个名为 withOptions 的方法，该方法接受一个新的选项对象 newOptions
+    // 并返回一个新的 LoggerForType 实例，该实例的类型和当前实例相同，但选项是合并后的结果
     result.withOptions = newOptions => this.wrapType(result.type, { ...result.options, ...newOptions });
+    // 返回 result 对象，该对象是一个新的 LoggerForType 实例
     return result;
   }
+
+  // 创建一个用于记录调试信息的日志记录器
   public debug = this.wrapType('DEBUG');
+
+  // 创建一个用于记录一般信息的日志记录器
   public info = this.wrapType('INFO');
+
+  /**
+   * 创建一个用于记录警告信息的日志记录器，并设置了一些额外的选项
+   * @param callStacktrace - 调用堆栈跟踪的深度
+   * @param reportedFromLevel - 报告的起始级别
+   */
   public warning = this.wrapType('WARNING', { callStacktrace: 3, reportedFromLevel: 2 });
+
+  /**
+   * 创建一个用于记录错误信息的日志记录器，并设置了一些额外的选项
+   * @param callStacktrace - 调用堆栈跟踪的深度
+   * @param reportedFromLevel - 报告的起始级别
+   * @param maxErrorStack - 最大错误堆栈跟踪深度
+   */
   public error = this.wrapType('ERROR', { callStacktrace: 5, reportedFromLevel: 2, maxErrorStack: 10 });
 }
 
+// 导出 Logger 类型，以便在其他文件中使用
 export type { Logger };
 
+/**
+ * 增加日志记录选项中的堆栈跟踪偏移量
+ * @param amount - 要增加的堆栈跟踪偏移量，默认为 1
+ * @param options - 日志记录选项
+ * @returns 一个新的日志记录选项对象，其中堆栈跟踪偏移量增加了指定的 amount
+ */
 export function withStacktraceOffset(amount: number = 1, options: Partial<LoggingOptions> = {}): Partial<LoggingOptions> {
   return { ...options, callStacktraceOffset: (options.callStacktraceOffset || 0) + amount };
 }
 
+/**
+ * 定义一个接口，继承自 FileSystemConfig 并省略了 sock 和 _calculated 属性
+ * 同时重新定义了这两个属性，使其为可选的字符串类型
+ * 此外，_calculated 属性的类型是 CensoredFileSystemConfig 类型，允许嵌套
+ */
 export interface CensoredFileSystemConfig extends Omit<FileSystemConfig, 'sock' | '_calculated'> {
+  // 可选的 sock 属性，用于存储套接字信息
   sock?: string;
+  // 可选的 _calculated 属性，用于存储计算后的值
   _calculated?: CensoredFileSystemConfig;
 }
 
+/**
+ * 审查配置对象，将敏感信息替换为 `<censored>`
+ * @param config - 要审查的文件系统配置对象
+ * @returns 审查后的文件系统配置对象，其中敏感信息已被替换
+ */
 function censorConfig(config: FileSystemConfig): CensoredFileSystemConfig {
   return {
+    // 复制 config 对象的所有属性
     ...config,
+    // 如果 password 是字符串类型，则替换为 <censored>
     password: typeof config.password === 'string' ? '<censored>' : config.password,
+    // 如果 passphrase 是字符串类型，则替换为 <censored>
     passphrase: typeof config.passphrase === 'string' ? '<censored>' : config.passphrase,
+    // 如果 privateKey 是 Buffer 类型，则替换为 Buffer(长度)
     privateKey: config.privateKey instanceof Buffer ? `Buffer(${config.privateKey.length})` : config.privateKey,
+    // 如果 sock 存在，则替换为 <socket>
     sock: config.sock ? '<socket>' : config.sock,
+    // 如果 _calculated 存在，则递归调用 censorConfig 函数进行审查
     _calculated: config._calculated ? censorConfig(config._calculated) : config._calculated,
   };
 }
 
+/**
+ * 创建一个全局的日志记录器实例
+ * 这个实例是 Logger 类的一个实例，用于记录应用程序的日志信息
+ */
 export const Logging = new (Logger as any) as Logger;
 
+// 在全局日志记录器中记录一条信息
 Logging.info`
 Created output channel for vscode-sshfs
 When posting your logs somewhere, keep the following in mind: