Fix RouteAware.didPushNext documentation inaccuracy#183097
Fix RouteAware.didPushNext documentation inaccuracy#183097ishaquehassan wants to merge 4 commits intoflutter:masterfrom
Conversation
The documentation incorrectly states that didPushNext is called when "the current route is no longer visible". In reality, didPushNext is called synchronously during the push operation, before the transition animation completes. At this point, the current route may still be partially visible as it animates out. This commit corrects the documentation to accurately describe the timing and provides guidance on how to detect when a route is fully obscured. Fixes flutter#24594
There was a problem hiding this comment.
Code Review
This pull request updates the documentation for RouteAware.didPushNext to clarify that it's called before the route transition animation completes. The change is accurate and improves the documentation. I've suggested adding a small code example to further illustrate how to perform actions after the animation is complete, which would make the documentation even more helpful for developers.
| /// Called when a new route has been pushed. | ||
| /// | ||
| /// Note that this is called during the push operation, before the transition | ||
| /// animation completes. At this point the current route may still be | ||
| /// partially visible as it animates out. To perform actions after the route | ||
| /// is fully obscured, consider using [ModalRoute.animation] to listen for | ||
| /// animation completion. |
There was a problem hiding this comment.
This documentation update is a great improvement in accuracy. To make it even more helpful for developers, consider adding a small code snippet showing how to use ModalRoute.animation as you've suggested. This aligns with the Flutter style guide's recommendation to provide sample code where helpful.
/// Called when a new route has been pushed.
///
/// Note that this is called during the push operation, before the transition
/// animation completes. At this point the current route may still be
/// partially visible as it animates out. To perform actions after the route
/// is fully obscured, consider using [ModalRoute.animation] to listen for
/// animation completion, for example:
///
/// ```dart
/// ModalRoute.of(context)?.animation?.addStatusListener((AnimationStatus status) {
/// if (status == AnimationStatus.completed) {
/// // The new route is now fully visible and the old route is fully obscured.
/// }
/// });
/// ```References
- The style guide recommends providing sample code to make documentation more useful. Adding a snippet for
ModalRoute.animationwould be a good example of this. (link)
There was a problem hiding this comment.
Thanks for the suggestion! I've added a code snippet demonstrating how to use ModalRoute.animation with a status listener, as recommended. This should make it clearer for developers how to perform actions after the transition animation fully completes.
The documentation for
RouteAware.didPushNextincorrectly states that the method is called when "the current route is no longer visible". However, tracing through the source code inroutes.dartshows thatdidPushNextis called synchronously during the push operation inRouteObserver.didPush(), before the transition animation completes. At this point, the current route may still be partially visible as it animates out.This PR corrects the documentation to accurately describe when
didPushNextis called and provides guidance for developers who need to perform actions after the route is fully obscured.This PR implements the analysis from my earlier comment on this issue.
Fixes #24594
Pre-launch Checklist
///).If you need help, consider asking for advice on the #hackers-new channel on Discord.
Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the
gemini-code-assistbot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.