From 594efdd63c1815ce7527a3a67a6854e45c158e28 Mon Sep 17 00:00:00 2001
From: Brian Wilkerson <brianwilkerson@google.com>
Date: Wed, 10 Jun 2026 12:21:26 -0700
Subject: [PATCH] Add documentation for another warning

Change-Id: If31cfea7c3dc3379cc0e8eda454ac9fdec4a348d
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/503942
Reviewed-by: Connie Ooi <connieooi@google.com>
Auto-Submit: Brian Wilkerson <brianwilkerson@google.com>
Commit-Queue: Brian Wilkerson <brianwilkerson@google.com>
---
 pkg/analyzer/messages.yaml | 57 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/pkg/analyzer/messages.yaml b/pkg/analyzer/messages.yaml
index 4422019a1a0..f095aadeb09 100644
--- a/pkg/analyzer/messages.yaml
+++ b/pkg/analyzer/messages.yaml
@@ -28177,6 +28177,63 @@ WarningCode:
     sharedName: invalidReturnTypeForThen
     problemMessage: "The return type '#actualType' isn't assignable to '#expectedType', as required by 'Future.then'."
     hasPublishedDocs: false
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when the return type of the
+      `onError` argument in `Future.then` is incompatible with the return type
+      of the `onValue` argument. At runtime, `Future.then` attempts to return
+      the value from the `onError` handler as the future's result, which
+      throws another exception.
+
+      #### Examples
+
+      The following code produces this diagnostic because the `onError` handler
+      returns a `String` instead of an `int`:
+
+      ```dart
+      void f(Future<int> future) {
+        future.then((_) => 0, onError: (e, st) => [!'c'!]);
+      }
+      ```
+
+      The following code produces this diagnostic because the return type of the
+      `onError` argument (`cb`) is incompatible with the return type of
+      `onValue`:
+
+      ```dart
+      void f(Future<int> future, String Function(dynamic, StackTrace) cb) {
+        future.then<int>((_) => 1, onError: [!cb!]);
+      }
+      ```
+
+      #### Common fixes
+
+      If the `onValue` handler returns the correct type, then change the
+      `onError` handler to match:
+
+      ```dart
+      void f(Future<int> future) {
+        future.then((_) => 0, onError: (e, st) => -1);
+      }
+      ```
+
+      If the `onError` handler is correct, then change the `onValue` handler to
+      match:
+
+      ```dart
+      void f(Future<String> future) {
+        future.then((_) => 'a', onError: (e, st) => 'c');
+      }
+      ```
+
+      If both handlers are correct, then change the future type to match:
+
+      ```dart
+      void f(Future<String> future) {
+        future.then<Object>((_) => 0, onError: (e, st) => 'c');
+      }
+      ```
   invalidReopenAnnotation:
     type: staticWarning
     parameters: none