Document potential user expectation of ctrl+left click behavior on macOS. (#4518)

winit-core/src/event.rs

@@ -516,6 +516,19 @@ impl From<PointerSource> for PointerKind {
 /// system.
 #[derive(Clone, Debug, PartialEq)]
 pub enum ButtonSource {
+    /// ## Platform-specific
+    ///
+    /// ### macOS
+    ///
+    /// Users may expect holding [<kbd>CTRL</kbd>](ModifiersState::CONTROL) while
+    /// clicking [`MouseButton::Left`] to result in a "secondary" click, but the way these
+    /// clicks behave natively is slightly different from how a physical secondary
+    /// button press would, depending on the content under the cursor when clicked. If
+    /// applications want this behavior they should implement it themselves by interpreting
+    /// [`Left`](MouseButton::Left) clicks as secondary when
+    /// [<kbd>CTRL</kbd>](ModifiersState::CONTROL) is held and their internal logic deems it
+    /// appropriate for the content under the pointer.
+    /// See also https://github.com/rust-windowing/winit/issues/4469.
     Mouse(MouseButton),
     /// See [`PointerSource::Touch`] for more details.
     ///