chore: add jsDoc for more configurations (#657)

Timeless0911 · web-flow · commit 9dc4a4829319 · 2025-01-07T17:23:30.000+08:00
diff --git a/packages/core/src/types/config.ts b/packages/core/src/types/config.ts
@@ -1,5 +1,4 @@
 import type { EnvironmentConfig, RsbuildConfig, Rspack } from '@rsbuild/core';
-import type { PluginDtsOptions } from 'rsbuild-plugin-dts';
 import type { GetAsyncFunctionFromUnion } from './utils';
 
 export type Format = 'esm' | 'cjs' | 'umd' | 'mf';
@@ -44,21 +43,67 @@ export type Syntax =
   | string[];
 
 export type Dts =
-  | (Pick<
-      PluginDtsOptions,
-      'bundle' | 'distPath' | 'abortOnError' | 'build'
-    > & {
+  | {
+      /**
+       * Whether to bundle the DTS files.
+       * @defaultValue `false`
+       * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsbundle}
+       */
+      bundle?: boolean;
+      /**
+       * The output directory of DTS files.
+       * @defaultValue {@link https://lib.rsbuild.dev/config/lib/dts#default-value}
+       * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsdistpath}
+       */
+      distPath?: string;
+      /**
+       * Whether to generate DTS files with building the project references.
+       * @defaultValue `false`
+       * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsbuild}
+       */
+      build?: boolean;
+      /**
+       * Whether to abort the build process when an error occurs during DTS generation.
+       * @defaultValue `true`
+       * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsabortonerror}
+       */
+      abortOnError?: boolean;
+      /**
+       * Whether to automatically set the DTS file extension based on the {@link format} option.
+       * @defaultValue `false`
+       * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsautoextension}
+       */
       autoExtension?: boolean;
-    })
+    }
   | boolean;
 
 export type AutoExternal =
   | boolean
   | {
+      /**
+       * Whether to automatically externalize dependencies of type `dependencies`.
+       * @defaultValue `true`
+       * @see {@link https://lib.rsbuild.dev/config/lib/auto-external#autoexternaldependencies}
+       */
       dependencies?: boolean;
+      /**
+       * Whether to automatically externalize dependencies of type `optionalDependencies`.
+       * @defaultValue `true`
+       * @see {@link https://lib.rsbuild.dev/config/lib/auto-external#autoexternaloptionaldependencies}
+       */
       optionalDependencies?: boolean;
-      devDependencies?: boolean;
+      /**
+       * Whether to automatically externalize dependencies of type `peerDependencies`.
+       * @defaultValue `true`
+       * @see {@link https://lib.rsbuild.dev/config/lib/auto-external#autoexternalpeerdependencies}
+       */
       peerDependencies?: boolean;
+      /**
+       * Whether to automatically externalize dependencies of type `devDependencies`.
+       * @defaultValue `false`
+       * @see {@link https://lib.rsbuild.dev/config/lib/auto-external#autoexternaldevdependencies}
+       */
+      devDependencies?: boolean;
     };
 
 export type BannerAndFooter = {
@@ -68,12 +113,40 @@ export type BannerAndFooter = {
 };
 
 export type Shims = {
+  /**
+   * Configure the shims for CommonJS output.
+   * @see {@link https://lib.rsbuild.dev/config/lib/shims#shimscjs}
+   */
   cjs?: {
+    /**
+     * Whether to inject shims for the `import.meta.url` in CommonJS output.
+     * @defaultValue `true`
+     * @see {@link https://lib.rsbuild.dev/config/lib/shims#shimscjsimportmetaurl}
+     */
     'import.meta.url'?: boolean;
   };
+  /**
+   * Configure the shims for ESM output.
+   * @see {@link https://lib.rsbuild.dev/config/lib/shims#shimsesm}
+   */
   esm?: {
+    /**
+     * Whether to inject shims for the global `__filename` of CommonJS in ESM output.
+     * @defaultValue `false`
+     * @see {@link https://lib.rsbuild.dev/config/lib/shims#shimsesm__filename}
+     */
     __filename?: boolean;
+    /**
+     * Whether to inject shims for the global `__dirname` of CommonJS in ESM output.
+     * @defaultValue `false`
+     * @see {@link https://lib.rsbuild.dev/config/lib/shims#shimsesm__dirname}
+     */
     __dirname?: boolean;
+    /**
+     * Whether to inject shims for the global `require` of CommonJS in ESM output.
+     * @defaultValue `false`
+     * @see {@link https://lib.rsbuild.dev/config/lib/shims#shimsesmrequire}
+     */
     require?: boolean;
   };
 };
@@ -85,7 +158,7 @@ export type JsRedirect = {
    */
   path?: boolean;
   /**
-   * Whether to automatically add the file extension to import paths based on the JavaScript output files.
+   * Whether to automatically redirect the file extension to import paths based on the JavaScript output files.
    * @defaultValue `true`
    */
   extension?: boolean;
@@ -98,7 +171,7 @@ export type StyleRedirect = {
    */
   path?: boolean;
   /**
-   * Whether to automatically add the file extension to import paths based on the style output files.
+   * Whether to automatically redirect the file extension to import paths based on the style output files.
    * @defaultValue `true`
    */
   extension?: boolean;
@@ -113,7 +186,7 @@ type DtsRedirect = {
 export type Redirect = {
   /** Controls the redirect of the import paths of output JavaScript files. */
   js?: JsRedirect;
-  /** Whether to redirect the import path of the style file. */
+  /** Controls the redirect of the import paths of output style files. */
   style?: StyleRedirect;
   // TODO: support other redirects
   // asset?: boolean;
diff --git a/packages/plugin-dts/README.md b/packages/plugin-dts/README.md
@@ -75,7 +75,7 @@ pluginDts({
 - **Type:** `boolean`
 - **Default:** `false`
 
-Determines whether to generate DTS files while building the project references. This is equivalent to using the `--build` flag with the `tsc` command. See [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) for more details.
+Whether to generate DTS files with building the project references. This is equivalent to using the `--build` flag with the `tsc` command. See [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) for more details.
 
 When this option is enabled, you must explicitly set `declarationDir` or `outDir` in `tsconfig.json` in order to meet the build requirements.
 
diff --git a/website/docs/en/config/lib/dts.mdx b/website/docs/en/config/lib/dts.mdx
@@ -130,7 +130,7 @@ export default {
 - **Type:** `boolean`
 - **Default:** `false`
 
-Determines whether to generate DTS files while building the project references. This is equivalent to using the `--build` flag with the `tsc` command. See [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) for more details.
+Whether to generate DTS files with building the project references. This is equivalent to using the `--build` flag with the `tsc` command. See [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) for more details.
 
 ::: note
 
diff --git a/website/docs/en/config/lib/redirect.mdx b/website/docs/en/config/lib/redirect.mdx
@@ -95,7 +95,7 @@ When set to `false`, the import path will not be effected by [resolve.alias](/co
 
 ### redirect.js.extension
 
-Whether to automatically add the file extension to import paths based on the JavaScript output files.
+Whether to automatically redirect the file extension to import paths based on the JavaScript output files.
 
 - **Type:** `boolean`
 - **Default:** `true`
@@ -106,9 +106,11 @@ When set to `false`, the file extension will remain unchanged from the original
 
 ## redirect.style
 
+Controls the redirect of the import paths of output style files.
+
 ### redirect.style.path
 
-Whether to automatically redirect the import path when importing style files, the rules are the same as [redirect.js.path](/config/lib/redirect#redirectjspath).
+Whether to automatically redirect the import paths of style output files, the rules are the same as [redirect.js.path](/config/lib/redirect#redirectjspath).
 
 - **Type:** `boolean`
 - **Default:** `true`
@@ -137,7 +139,7 @@ import styles from '../foo.css'; // expected output of './dist/utils/index.js'
 
 ### redirect.style.extension
 
-Whether to redirect style file extensions.
+Whether to automatically redirect the file extension to import paths based on the style output files.
 
 - **Type:** `boolean`
 - **Default:** `true`
diff --git a/website/docs/en/config/lib/shims.mdx b/website/docs/en/config/lib/shims.mdx
@@ -42,6 +42,8 @@ Set the fields to `true` to enable the corresponding shims for CommonJS output.
 
 ### shims.cjs['import.meta.url']
 
+Whether to inject shims for the `import.meta.url` in CommonJS output.
+
 - **Default:** `true`
 
 Options:
@@ -82,7 +84,7 @@ Set the fields to `true` to enable the corresponding shims for ESM output.
 
 ### shims.esm.\_\_filename
 
-Whether to shim the global `__filename` of CommonJS in ESM output.
+Whether to inject shims for the global `__filename` of CommonJS in ESM output.
 
 - **Default:** `false`
 
@@ -112,7 +114,7 @@ Options:
 
 ### shims.esm.\_\_dirname
 
-Whether to shim the global `__dirname` of CommonJS in ESM output.
+Whether to inject shims for the global `__dirname` of CommonJS in ESM output.
 
 - **Default:** `false`
 
@@ -141,7 +143,7 @@ Options:
 
 ### shims.esm.require
 
-Whether to shim the global `require` of CommonJS in ESM output.
+Whether to inject shims for the global `require` of CommonJS in ESM output.
 
 - **Default:** `false`
 
diff --git a/website/docs/zh/config/lib/dts.mdx b/website/docs/zh/config/lib/dts.mdx
@@ -130,7 +130,7 @@ export default {
 - **类型：** `boolean`
 - **默认值：** `false`
 
-决定是否在构建项目引用时生成 DTS 文件。这相当于在 `tsc` 命令中使用 `--build` 标志。更多详细信息请参考 [项目引用](https://www.typescriptlang.org/docs/handbook/project-references.html)。
+是否在生成 DTS 文件时构建项目的 references。这相当于在 `tsc` 命令中使用 `--build` 标志。更多详细信息请参考 [项目引用](https://www.typescriptlang.org/docs/handbook/project-references.html)。
 
 ::: note
 
diff --git a/website/docs/zh/config/lib/redirect.mdx b/website/docs/zh/config/lib/redirect.mdx
@@ -6,7 +6,7 @@ overviewHeaders: [2, 3]
 
 :::info
 
-`redirect` 是 bundleless 模式（将 [lib.bundle](/config/lib/bundle) 设置为 `false`）的特定配置。在 bundle 模式下不会生效，因为所有输出文件都被打包成一个文件。所以，导入路径不存在因而不需要重定向。
+`redirect` 是 bundleless 模式（将 [lib.bundle](/config/lib/bundle) 设置为 `false`）的特定配置。在 bundle 模式下不会生效，因为所有产物文件都被打包成一个文件。所以，导入路径不存在因而不需要重定向。
 
 由于 bundleless 模式仍在开发中，未来将引入更多的重定向配置。
 
@@ -46,13 +46,13 @@ const defaultRedirect = {
 };
 ```
 
-配置输出文件中导入路径的重定向。在 bundleless 模式下，通常需要使用别名或自动添加 ESM 产物的后缀。`redirect` 配置旨在解决这些问题。
+配置产物文件中导入路径的重定向。在 bundleless 模式下，通常需要使用别名或自动添加 ESM 产物的后缀。`redirect` 配置旨在解决这些问题。
 
 常见的需要 redirect 的场景：
 
 - 自动将 tsconfig.json 中 `compilerOptions.paths` 转换为正确的相对路径
 
-  例如，在 tsconfig.json 中将 `compilerOptions.paths` 设置为 `{ "@/*": ["src/*"] }`，输出文件将被重定向到正确的相对路径：
+  例如，在 tsconfig.json 中将 `compilerOptions.paths` 设置为 `{ "@/*": ["src/*"] }`，产物文件将被重定向到正确的相对路径：
 
   ```ts
   import { foo } from '@/foo'; // './src/bar.ts' 的源码 ↓
@@ -64,7 +64,7 @@ const defaultRedirect = {
 
 - 自动添加文件后缀
 
-  对于在 Node.js 中运行的 ESM 产物，必须指定模块导入的完整路径才能正确加载。Rslib 将根据输出文件自动添加后缀。
+  对于在 Node.js 中运行的 ESM 产物，必须指定模块导入的完整路径才能正确加载。Rslib 将根产物文件自动添加后缀。
 
   ```ts
   import { foo } from './foo'; // './src/bar.ts'  的源码 ↓
@@ -76,39 +76,41 @@ const defaultRedirect = {
 
 ## redirect.js
 
-控制输出 JavaScript 文件导入路径的重定向。
+控制 JavaScript 产物文件导入路径的重定向。
 
 :::warning
 当 [output.externals](/config/rsbuild/output#outputexternals) 被配置且请求被匹配时，`redirect.js.path` 和 `redirect.js.extension` 都不会生效，最终重写的请求路径将完全由 [output.externals](/config/rsbuild/output#outputexternals) 控制。
 :::
 
 ### redirect.js.path
 
-是否自动重定向 JavaScript 输出文件的导入路径。
+是否自动重定向 JavaScript 产物文件的导入路径。
 
 - **类型:** `boolean`
 - **默认值:** `true`
 
-当设置为 `true` 时，[resolve.alias](/config/rsbuild/resolve#resolvealias) 和 [resolve.aliasStrategy](/config/rsbuild/resolve#aliasstrategy) 将生效并应用于输出文件的重写导入路径。对于 TypeScript 项目，您只需在 tsconfig.json 文件中配置 [compilerOptions.paths](https://typescriptlang.org/tsconfig#paths)。
+当设置为 `true` 时，[resolve.alias](/config/rsbuild/resolve#resolvealias) 和 [resolve.aliasStrategy](/config/rsbuild/resolve#aliasstrategy) 将生效并应用于产物文件的重写导入路径。对于 TypeScript 项目，您只需在 tsconfig.json 文件中配置 [compilerOptions.paths](https://typescriptlang.org/tsconfig#paths)。
 
 当设置为 `false` 时，导入路径将不受 [resolve.alias](/config/rsbuild/resolve#resolvealias)、[resolve.aliasStrategy](/config/rsbuild/resolve#aliasstrategy) 和 tsconfig.json 的影响。
 
 ### redirect.js.extension
 
-是否根据 JavaScript 输出文件自动添加文件扩展名到导入路径。
+是否根据 JavaScript 产物文件自动重定向文件扩展名到导入路径。
 
 - **类型:** `boolean`
 - **默认值:** `true`
 
-当设置为 `true` 时，无论原始扩展名或导入路径中是否指定，文件扩展名都将自动添加到输出文件的重写导入路径中。
+当设置为 `true` 时，无论原始扩展名或导入路径中是否指定，文件扩展名都将自动添加到产物文件的重写导入路径中。
 
 当设置为 `false` 时，文件扩展名将保持原始导入路径中的不变（无论是否指定或指定为任意值）。
 
 ## redirect.style
 
+控制样式产物文件导入路径的重定向。
+
 ### redirect.style.path
 
-导入样式文件时是否自动重定向导入路径，规则与 [redirect.js.path](/config/lib/redirect#redirectjspath) 相同。
+是否自动重定向样式产物文件的导入路径，规则与 [redirect.js.path](/config/lib/redirect#redirectjspath) 相同。
 
 - **类型:** `boolean`
 - **默认值:** `true`
@@ -137,12 +139,12 @@ import styles from '../foo.css'; // './dist/utils/index.js' 预期生成的代
 
 ### redirect.style.extension
 
-是否重定向样式文件的扩展名。
+是否根据样式产物文件自动重定向文件扩展名到导入路径。
 
 - **类型:** `boolean`
 - **默认值:** `true`
 
-当设置为 `true` 时，导入普通样式文件时，路径将被重写为 `.css` 文件，导入 [CSS Modules](/config/rsbuild/output#outputcssmodules) 时，路径将被重写为到对应的 JavaScript 输出文件。
+当设置为 `true` 时，导入普通样式文件时，路径将被重写为 `.css` 文件，导入 [CSS Modules](/config/rsbuild/output#outputcssmodules) 时，路径将被重写为到对应的 JavaScript 产物文件。
 
 当设置为 `false` 时，文件扩展名将保持原始导入路径中的不变。
 
diff --git a/website/docs/zh/config/lib/shims.mdx b/website/docs/zh/config/lib/shims.mdx
