We need the clamping physics to make nested scroll view work. If you turn off the clamping, it'll go crazy.

What if I want to provide my own class that extends ClampingScrollPhysics? Should we require that the physics argument be a ClampingScrollPhysics?

Specificially, this is the class I'd like to pass: https://github.com/flutter/flutter/blob/master/examples/flutter_gallery/lib/demo/animation/home.dart#L371

Yeah we could just require that the physics extend ClampingScrollPhysics for this subclass.

@abarth may have opinions, the crazy physics inheritance magic is his baby. ;-)

this sentence's grammar got garbled, not sure what you meant exactly

Defaults to [ClampingScrollPhysics]. is probably better.

Passing a custom class that extends [ClampingScrollPhysics] is allowed. is probably self-evident so I would omit it.
Maybe instead say something like The value must inherit from [ClampingScrollPhysics] and its [ScrollPhysics.applyBoundaryConditions] implementation should not allow scrolling outside the scroll extent range described by the [ScrollMetrics.minScrollExtent]/[ScrollMetrics.maxScrollExtent] properties passed to that method. If that invariant is not maintained, the nested scroll view may respond to user scrolling erratically. or some such.

You removed this sentence. Maybe consider bringing it back but having it point explicitly to [ScrollPhysics.createBallisticSimulation], which is the main method that one might want to override.

Thinking about it, a better fix (which would allow us to skip all the stuff about forcing the user to use ClampingScrollPhysics et al) would be to just use const ClampingScrollPhysics().applyTo(physics) in the case where physics is non-null.

er, other way around I guess. physics.applyTo(const ClampingScrollPhysics()). Whichever way makes the physics that was passed in take priority. You'd still need to explicitly call out that you shouldn't override the clamping method, though.

This works, so I made the change and reverted my other changes to documentation