From 056f12236e71ace505b3b366cdb236816be81774 Mon Sep 17 00:00:00 2001
From: Federico Rinaldi <gisquerin@gmail.com>
Date: Sun, 26 Jun 2022 13:40:43 +0000
Subject: [PATCH] Update `MouseMotion` and `CursorMoved` docs (#5090)

# Objective

- Fixes #5083

## Solution

I looked at the implementation of those events. I noticed that they both are adaptations of `winit`'s `DeviceEvent`/`WindowEvent` enum variants. Therefore I based the description of the items on the documentation provided by the upstream crate. I also added a link to `CursorMoved`, just like `MouseMotion` already has.

## Observations

- Looking at the implementation of `MouseMotion`, I noticed the `DeviceId` field of the `winit` event is discarded by `bevy_input`. This means that in the case a machine has multiple pointing devices, it is impossible to distinguish to which one the event is referring to. **EDIT:** just tested, `MouseMotion` events are emitted for movement of both mice.
---
 crates/bevy_input/src/mouse.rs  | 12 +++++++++---
 crates/bevy_window/src/event.rs | 13 ++++++++++++-
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/crates/bevy_input/src/mouse.rs b/crates/bevy_input/src/mouse.rs
index c8dc432094..b06a5c2ae3 100644
--- a/crates/bevy_input/src/mouse.rs
+++ b/crates/bevy_input/src/mouse.rs
@@ -41,12 +41,18 @@ pub enum MouseButton {
     Other(u16),
 }
 
-/// A mouse motion event.
+/// An event reporting the change in physical position of a pointing device.
 ///
-/// This event is the translated version of the `DeviceEvent::MouseMotion` from the `winit` crate.
+/// This represents raw, unfiltered physical motion.
+/// It is the translated version of [`DeviceEvent::MouseMotion`] from the `winit` crate.
+///
+/// All pointing devices connected to a single machine at the same time can emit the event independently.
+/// However, the event data does not make it possible to distinguish which device it is referring to.
+///
+/// [`DeviceEvent::MouseMotion`]: https://docs.rs/winit/latest/winit/event/enum.DeviceEvent.html#variant.MouseMotion
 #[derive(Debug, Clone)]
 pub struct MouseMotion {
-    /// The delta of the previous and current mouse positions.
+    /// The change in the position of the pointing device since the last event was sent.
     pub delta: Vec2,
 }
 
diff --git a/crates/bevy_window/src/event.rs b/crates/bevy_window/src/event.rs
index c57222973b..0ac0d01c2d 100644
--- a/crates/bevy_window/src/event.rs
+++ b/crates/bevy_window/src/event.rs
@@ -58,10 +58,21 @@ pub struct WindowCloseRequested {
 pub struct WindowClosed {
     pub id: WindowId,
 }
-/// An event that is sent whenenver the user's cursor moves.
+/// An event reporting that the mouse cursor has moved on a window.
+///
+/// The event is sent only if the cursor is over one of the application's windows.
+/// It is the translated version of [`WindowEvent::CursorMoved`] from the `winit` crate.
+///
+/// Not to be confused with the [`MouseMotion`] event from `bevy_input`.
+///
+/// [`WindowEvent::CursorMoved`]: https://docs.rs/winit/latest/winit/event/enum.WindowEvent.html#variant.CursorMoved
+/// [`MouseMotion`]: bevy_input::mouse::MouseMotion
 #[derive(Debug, Clone)]
 pub struct CursorMoved {
+    /// The identifier of the window the cursor has moved on.
     pub id: WindowId,
+
+    /// The position of the cursor, in window coordinates.
     pub position: Vec2,
 }
 /// An event that is sent whenever the user's cursor enters a window.