-
Greg Price authored
Fixes #120341. The scroll protocol makes an important assumption about the behavior of ScrollPhysics implementations, and this requirement hasn't been clearly documented. Add documentation for it. Parts of the text are modelled on similar language at StatelessWidget.build and StatefulWidget.build. It does feel a bit uncomfortable to juxtapose this description of a required invariant with three issues where the framework doesn't satisfy it. Fortunately two of them apply by default only in uncommon cases: #120340 macOS touchpad flinging, and #109675 never. The third is #120338, affecting default scrolling on Android and other non-Apple platforms. I'll send a PR to fix that shortly, and another for #109675. As discussed at #120338, it's quite possible we'll remove this invariant in the future. But that's been attempted before, and is complicated: the invariant is a useful one. Removing it would almost certainly involve a breaking change for ScrollPhysics subclasses. So I think even if we had an immediate plan to remove it, we'd need some kind of documentation for it, if only to explain the breaking change.