From 4d7ea685bd9de004bffe276e24e966400b98e818 Mon Sep 17 00:00:00 2001
From: Peter Leibiger <kuhnroyal@gmail.com>
Date: Thu, 28 Sep 2023 20:16:20 +0200
Subject: [PATCH] Improve docs for LogInterceptor (#1971)

<!-- Write down your pull request descriptions. -->

* closes #1970


### New Pull Request Checklist

- [x] I have read the
[Documentation](https://pub.dev/documentation/dio/latest/)
- [x] I have searched for a similar pull request in the
[project](https://github.com/cfug/dio/pulls) and found none
- [x] I have updated this branch with the latest `main` branch to avoid
conflicts (via merge from master or rebase)
- [ ] I have added the required tests to prove the fix/feature I'm
adding
- [x] I have updated the documentation (if necessary)
- [ ] I have run the tests without failures
- [ ] I have updated the `CHANGELOG.md` in the corresponding package

### Additional context and info (if any)

<!-- Provide more context and info about the PR. -->

---------

Co-authored-by: Alex Li <github@alexv525.com>
---
 dio/README-ZH.md                  | 30 +++++++++++++++++++++++++++---
 dio/README.md                     | 30 +++++++++++++++++++++++++++---
 dio/lib/src/interceptors/log.dart | 16 ++++++++++++++--
 3 files changed, 68 insertions(+), 8 deletions(-)

diff --git a/dio/README-ZH.md b/dio/README-ZH.md
index 740aee206..0e06ee863 100644
--- a/dio/README-ZH.md
+++ b/dio/README-ZH.md
@@ -469,15 +469,39 @@ print(response.data); // 'fake data'
 
 #### 日志拦截器
 
-我们可以添加 `LogInterceptor` 拦截器来自动打印请求、响应日志：
+我们可以添加 `LogInterceptor` 拦截器来自动打印请求和响应等日志：
+
+**注意：** `LogInterceptor` 应该保持最后一个被添加到拦截器中，
+否则在它之后进行处理的拦截器修改的内容将无法体现。
+
+#### Dart
 
 ```dart
 dio.interceptors.add(LogInterceptor(responseBody: false)); // 不输出响应内容体
 ```
 
-**注意：** 由于拦截器队列是先进先出，`LogInterceptor` 应当在最后添加至 `Dio` 实例。
+**注意：** 默认的 `logPrint` 只会在 DEBUG 模式（启用了断言）
+的情况下输出日志。
+
+你也可以使用 `dart:developer` 中的 `log` 来输出日志（在 Flutter 中也可以使用）。
+
+#### Flutter
+
+在 Flutter 中你应该使用 `debugPrint` 来打印日志。
+
+这样也会让调试日志能够通过 `flutter logs` 获取到。
 
-**注意：** 日志默认仅在 DEBUG 模式（启用了断言）下打印。
+**注意：** `debugPrint` 的意义 **不是只在 DEBUG 模式下打印**，
+而是对输出内容进行节流，从而保证输出完整。
+请不要在生产模式使用，除非你有意输出相关日志。
+
+```dart
+dio.interceptors.add(
+  LogInterceptor(
+    logPrint: (o) => debugPrint(o.toString()),
+  ),
+);
+```
 
 ### 自定义拦截器
 
diff --git a/dio/README.md b/dio/README.md
index b2ba69d01..a77ef77b4 100644
--- a/dio/README.md
+++ b/dio/README.md
@@ -484,15 +484,39 @@ For the complete code see [here](../example/lib/queued_interceptor_crsftoken.dar
 
 #### LogInterceptor
 
-You can apply the `LogInterceptor` to log requests and responses automatically in the DEBUG mode:
+You can apply the `LogInterceptor` to log requests and responses automatically.
+
+**Note:** `LogInterceptor` should always be the last interceptor added,
+otherwise modifications by following interceptors will not be logged.
+
+#### Dart
 
 ```dart
 dio.interceptors.add(LogInterceptor(responseBody: false)); // Do not output responses body.
 ```
 
-**Note:** `LogInterceptor` should be the last to add since the interceptors are FIFO.
+**Note:** When using the default `logPrint` function, logs will only be printed
+in DEBUG mode (when the assertion is enabled).
+
+Alternatively `dart:developer`'s log can also be used to log messages (available in Flutter too).
+
+#### Flutter
+
+When using Flutter, Flutters own `debugPrint` function should be used.
+
+This ensures, that debug messages are also available via `flutter logs`.
 
-**Note:** Logs will only be printed in the DEBUG mode (when the assertion is enabled).
+**Note:** `debugPrint` **does not mean print logs under the DEBUG mode**,
+it's a throttled function which helps to print full logs without truncation.
+Do not use it under any production environment unless you're intended to.
+
+```dart
+dio.interceptors.add(
+  LogInterceptor(
+    logPrint: (o) => debugPrint(o.toString()),
+  ),
+);
+```
 
 #### Custom Interceptor
 
diff --git a/dio/lib/src/interceptors/log.dart b/dio/lib/src/interceptors/log.dart
index 04f647077..682384334 100644
--- a/dio/lib/src/interceptors/log.dart
+++ b/dio/lib/src/interceptors/log.dart
@@ -4,9 +4,21 @@ import '../options.dart';
 import '../response.dart';
 
 /// [LogInterceptor] is used to print logs during network requests.
-/// It's better to add [LogInterceptor] to the tail of the interceptor queue,
-/// otherwise the changes made in the interceptor behind A will not be printed out.
+/// It should be the last interceptor added,
+/// otherwise modifications by following interceptors will not be logged.
 /// This is because the execution of interceptors is in the order of addition.
+///
+/// **Note**
+/// When used in Flutter, make sure to use `debugPrint` to print logs.
+/// Alternatively `dart:developer`'s `log` function can also be used.
+///
+/// ```dart
+/// dio.interceptors.add(
+///   LogInterceptor(
+///    logPrint: (o) => debugPrint(o.toString()),
+///   ),
+/// );
+/// ```
 class LogInterceptor extends Interceptor {
   LogInterceptor({
     this.request = true,