Document when each Qt::ScrollPhase will occur

I think it's pretty clear that ScrollBegin should come first, followed by ScrollUpdate, but it's not clear if ScrollEnd or ScrollMomentum should come 3rd, if the two are meant to be mutually exclusive or if it shouldn't matter whether either or both are used.

MacOS allows you to detect when a scroll gesture might begin (device has 2 fingers) with touchpads, but not with the magic mouse according to https://developer.apple.com/documentation/appkit/nsevent/1533550-phase?language=objc. If I understand qtbase/src/plugins/platforms/cocoa/qnsview_mouse.mm correctly, Qt maps both NSEventPhaseBegan and NSEventPhaseMayBegin to Qt::ScrollBegin, so you can't assume ScrollBegin always means the same thing on MacOS.

Linux doesn't have a direct way to detect when a scroll gesture might begin. If you know what the scrolling gesture is supposed to be (usually device has 2 fingers), you can detect it before scrolling actually begins, but there isn't an API in Qt for detecting what the scroll gesture should be or when it might begin. With Libinput on Wayland, ScrollBegin is always immediately followed by an event with ScrollUpdate, which makes the ScrollBegin phase a bit pointless. The event with ScrollUpdate has more useful info, so you can wait for the first ScrollUpdate to do all the logic related to beginning a scroll gesture.

If you have 2 QQuickItems stacked over each other that can accept wheel events but one scrolls vertically and the other horizontally, you can't tell which QQuickItem the user meant to begin scrolling on until the ScrollUpdate phase. Events with ScrollBegin always have null deltas, so you can't tell which direction the user wants to scroll. If you depend on ScrollBegin to stop momentum scrolling and set things up before an event with ScrollUpdate, you will not always affect the correct item unless you never accept events with ScrollBegin. Perhaps events with ScrollBegin aren't meant to be accepted, but this is not clear.

I realize some of these are not Qt issues directly, but it shows how you cannot depend very much on Qt to help you create a good cross platform implementation of scrolling that treats normal mouse and gesture scrolling differently.

What I would like is a way to reliably know when and how to use each phase without having to understand the quirks of various drivers on Linux, MacOS and Windows. Right now, ScrollPhase is not a great abstraction.