💡 Improve docs and comments about options merging (cfug#2240)

kuhnroyal · Jun 10, 2024 · 3eb2f4e · 3eb2f4e
1 parent d334d25
commit 3eb2f4e
Show file tree

Hide file tree

Showing 3 changed files with 18 additions and 9 deletions.
diff --git a/dio/README-ZH.md b/dio/README-ZH.md
@@ -282,9 +282,9 @@ final response = await dio.request(
 
 ### 请求配置
 
-`BaseOptions` 描述的是 Dio 实例发起网络请求的的公共配置，
-而 `Options` 描述了每一个Http请求的配置信息，每一次请求都可以单独配置，
-单次请求的 `Options` 中的配置信息可以覆盖 `BaseOptions` 中的配置。
+在 Dio 中有两种配置概念：`BaseOptions` 和 `Options`。
+`BaseOptions` 描述的是 Dio 实例的一套基本配置，而 `Options` 描述了单独请求的配置信息。
+以上的配置会在发起请求时进行合并。
 下面是 `Options` 的配置项：
 
 ```dart

diff --git a/dio/README.md b/dio/README.md
@@ -265,10 +265,12 @@ final response = await dio.request(
 
 ### Request Options
 
-The `Options` class describes the HTTP request information and configuration.
-Each Dio instance has a base config for all requests made by itself,
-and we can override the base config with `Options` when make a single request.
-The `Options` declaration as follows:
+There are two request options concepts in the Dio library:
+`BaseOptions` and `Options`.
+The `BaseOptions` include a set of base settings for each `Dio()`,
+and the `Options` describes the configuration for a single request.
+These options will be merged when making requests.
+The `Options` declaration is as follows:
 
 ```dart
 /// The HTTP request method.

diff --git a/dio/lib/src/options.dart b/dio/lib/src/options.dart
@@ -133,7 +133,11 @@ mixin OptionsMixin {
   }
 }
 
-/// The base config for the Dio instance, used by [Dio.options].
+/// A set of base settings for each `Dio()`.
+/// {@template dio.options.compose_merging}
+/// [BaseOptions] and [Options] will be merged into one [RequestOptions] before
+/// sending the requests. See [Options.compose].
+/// {@endtemplate}
 class BaseOptions extends _RequestConfig with OptionsMixin {
   BaseOptions({
     super.method,
@@ -209,7 +213,8 @@ class BaseOptions extends _RequestConfig with OptionsMixin {
   }
 }
 
-/// Every request can pass an [Options] object which will be merged with [Dio.options]
+/// The configuration for a single request.
+/// {@macro dio.options.compose_merging}
 class Options {
   Options({
     this.method,
@@ -292,6 +297,8 @@ class Options {
     );
   }
 
+  /// Merge a [BaseOptions] with the current [Options]
+  /// and compose them into the [RequestOptions].
   RequestOptions compose(
     BaseOptions baseOpt,
     String path, {