From 805cd4816d17c6bebb942bd7390d4e5ef5f19935 Mon Sep 17 00:00:00 2001
From: gmackall <34871572+gmackall@users.noreply.github.com>
Date: Fri, 23 Jun 2023 07:21:55 -0700
Subject: [PATCH] Add a note in ImeSyncDeferringInsetsCallback explaining the
 reason behind capturing the latest final inset state (flutter/engine#43109)

Solely documentation change to explain the reasoning behind the change in https://github.com/flutter/engine/pull/42700.

[C++, Objective-C, Java style guides]: https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#style
---
 .../plugin/editing/ImeSyncDeferringInsetsCallback.java      | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/engine/src/flutter/shell/platform/android/io/flutter/plugin/editing/ImeSyncDeferringInsetsCallback.java b/engine/src/flutter/shell/platform/android/io/flutter/plugin/editing/ImeSyncDeferringInsetsCallback.java
index c031276687b..a319a8ea264 100644
--- a/engine/src/flutter/shell/platform/android/io/flutter/plugin/editing/ImeSyncDeferringInsetsCallback.java
+++ b/engine/src/flutter/shell/platform/android/io/flutter/plugin/editing/ImeSyncDeferringInsetsCallback.java
@@ -68,6 +68,12 @@ class ImeSyncDeferringInsetsCallback {
   // When an animation begins, android sends a WindowInset with the final
   // state of the animation. When needsSave is true, we know to capture this
   // initial WindowInset.
+  //
+  // Certain actions, like dismissing the keyboard, can trigger multiple
+  // animations that are slightly offset in start time. To capture the
+  // correct final insets in these situations we update needsSave to true
+  // in each onPrepare callback, so that we save the latest final state
+  // to apply in onEnd.
   private boolean needsSave = false;
 
   ImeSyncDeferringInsetsCallback(@NonNull View view) {