docs: improve documentation for stats properties (#11792)

* docs: improve documentation for stats properties

* fix

Author: chenjiahan

packages/rspack/etc/core.api.md

@@ -1815,7 +1815,6 @@ type DevToolPosition = "inline-" | "hidden-" | "eval-" | "";
 
 // @public (undocumented)
 interface Diagnostic {
-    // (undocumented)
     file?: string;
     // (undocumented)
     help?: string;

packages/rspack/src/config/adapterRuleUse.ts

@@ -112,10 +112,13 @@ export interface Diagnostic {
 	sourceCode?: string;
 	/**
 	 * Location to the source code.
-	 *
 	 * If `sourceCode` is not provided, location will be omitted.
 	 */
 	location?: DiagnosticLocation;
+	/**
+	 * Optional filename to show.
+	 * If provided, it becomes the `StatsError.file` value in stats.
+	 */
 	file?: string;
 	severity: "error" | "warning";
 }

packages/rspack/src/stats/statsFactoryUtils.ts

@@ -185,8 +185,25 @@ export type KnownStatsError = {
 	chunkName?: string;
 	chunkEntry?: boolean;
 	chunkInitial?: boolean;
+	/**
+	 * A custom filename associated with this error/warning.
+	 */
 	file?: string;
+	/**
+	 * The identifier of the module related to this error/warning.
+	 * Usually an absolute path, may include inline loader requests.
+	 * @example
+	 * - `/path/to/project/src/index.js`
+	 * - `!builtin:react-refresh-loader!/path/to/project/src/index.css`
+	 */
 	moduleIdentifier?: string;
+	/**
+	 * The readable name of the module related to this error/warning.
+	 * Usually a relative path, no inline loader requests.
+	 * @example
+	 * - `"./src/index.js"`
+	 * - `"./src/index.css"`
+	 */
 	moduleName?: string;
 	loc?: string;
 	chunkId?: string | number;

website/docs/en/api/javascript-api/stats-json.mdx

@@ -315,16 +315,27 @@ Each error or warning object represents an error/warning thrown during the build
 type StatsError = {
   // Visual message of the error/warning
   message: string;
-  // Related source file
+  // A custom filename associated with this error/warning.
   file?: string;
   // Detail info of the error/warning
   details?: string;
   // Stack info of the error/warning
   stack?: string;
-
-  // Unique identifier of the module where the error/warning occurs
+  /**
+   * The identifier of the module related to this error/warning.
+   * Usually an absolute path, may include inline loader requests.
+   * @example
+   * - `/path/to/project/src/index.js`
+   * - `!builtin:react-refresh-loader!/path/to/project/src/index.css`
+   */
   moduleIdentifier?: string;
-  // Relative path of the module where the error/warning occurs
+  /**
+   * The readable name of the module related to this error/warning.
+   * Usually a relative path, no inline loader requests.
+   * @example
+   * - `"./src/index.js"`
+   * - `"./src/index.css"`
+   */
   moduleName?: string;
   // ID of the module where the error/warning occurs
   moduleId?: string;

website/docs/en/api/loader-api/context.mdx

@@ -221,10 +221,13 @@ interface Diagnostic {
   sourceCode?: string;
   /**
    * Location to the source code.
-   *
    * If `sourceCode` is not provided, location will be omitted.
    */
   location?: DiagnosticLocation;
+  /**
+   * Optional filename to show.
+   * If provided, it becomes the `StatsError.file` value in stats.
+   */
   file?: string;
   severity: 'error' | 'warning';
 }

website/docs/zh/api/javascript-api/stats-json.mdx

@@ -317,18 +317,27 @@ type StatsChunkGroup = {
 type StatsError = {
   // 错误/警告的可视化提示信息
   message: string;
-  // 相关资源文件
+  // 与此错误/警告关联的自定义文件名
   file?: string;
   // 错误/警告的明细信息
   details?: string;
   // 错误/警告的栈信息
   stack?: string;
-
-  // 发生错误/警告的模块唯一标识
+  /**
+   * 与此错误/警告相关的模块标识符
+   * 通常是绝对路径，可能包含内联的 loader request
+   * @example
+   * - `/path/to/project/src/index.js`
+   * - `!builtin:react-refresh-loader!/path/to/project/src/index.css`
+   */
   moduleIdentifier?: string;
-  // 发生错误/警告的模块相对路径
-  moduleName?: string;
-  // 发生错误/警告的模块 ID
+  /**
+   * 与此错误/警告相关的模块可读名称
+   * 通常是相对路径，不包含内联的 loader request
+   * @example
+   * - `"./src/index.js"`
+   * - `"./src/index.css"`
+   */
   moduleId?: string;
   // 错误/警告的模块引用路径
   moduleTrace: Array<JsStatsModuleTrace>;

website/docs/zh/api/loader-api/context.mdx

@@ -211,11 +211,14 @@ interface Diagnostic {
   help?: string;
   sourceCode?: string;
   /**
-   * Location to the source code.
-   *
-   * If `sourceCode` is not provided, location will be omitted.
+   * 源代码的位置信息
+   * 如果未提供 `sourceCode`，则位置信息将被省略
    */
   location?: DiagnosticLocation;
+  /**
+   * 可选展示的文件名
+   * 如果设置，它将成为 stats 中的 `StatsError.file` 值
+   */
   file?: string;
   severity: 'error' | 'warning';
 }