From c747951f4f1fcd2bcb6a4bb79142c5064dfed57d Mon Sep 17 00:00:00 2001
From: KDecay <kdecaymusic@protonmail.com>
Date: Tue, 26 Apr 2022 17:32:54 +0000
Subject: [PATCH] Update `mouse.rs` docs in `bevy_input` (#4518)

# Objective

- Part of the splitting process of #3692.

## Solution

- Document `mouse.rs` inside of `bevy_input`.

Co-authored-by: KDecay <KDecayMusic@protonmail.com>
---
 crates/bevy_input/src/mouse.rs | 61 ++++++++++++++++++++++++++++++----
 1 file changed, 54 insertions(+), 7 deletions(-)

diff --git a/crates/bevy_input/src/mouse.rs b/crates/bevy_input/src/mouse.rs
index 68f1540bb27fb8..c88c0295abffa7 100644
--- a/crates/bevy_input/src/mouse.rs
+++ b/crates/bevy_input/src/mouse.rs
@@ -2,46 +2,93 @@ use crate::{ButtonState, Input};
 use bevy_ecs::{event::EventReader, system::ResMut};
 use bevy_math::Vec2;
 
-/// A mouse button input event
+/// A mouse button input event.
+///
+/// This event is the translated version of the `WindowEvent::MouseInput` from the `winit` crate.
+///
+/// ## Usage
+///
+/// The event is read inside of the [`mouse_button_input_system`](crate::mouse::mouse_button_input_system)
+/// to update the [`Input<MouseButton>`](crate::Input<MouseButton>) resource.
 #[derive(Debug, Clone)]
 pub struct MouseButtonInput {
+    /// The mouse button assigned to the event.
     pub button: MouseButton,
+    /// The pressed state of the button.
     pub state: ButtonState,
 }
 
-/// A button on a mouse device
+/// A button on a mouse device.
+///
+/// ## Usage
+///
+/// It is used as the generic `T` value of an [`Input`](crate::Input) to create a `bevy`
+/// resource.
+///
+/// ## Updating
+///
+/// The resource is updated inside of the [`mouse_button_input_system`](crate::mouse::mouse_button_input_system).
 #[derive(Debug, Hash, PartialEq, Eq, Clone, Copy)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
 pub enum MouseButton {
+    /// The left mouse button.
     Left,
+    /// The right mouse button.
     Right,
+    /// The middle mouse button.
     Middle,
+    /// Another mouse button with the associated number.
     Other(u16),
 }
 
-/// A mouse motion event
+/// A mouse motion event.
+///
+/// This event is the translated version of the `DeviceEvent::MouseMotion` from the `winit` crate.
 #[derive(Debug, Clone)]
 pub struct MouseMotion {
+    /// The delta of the previous and current mouse positions.
     pub delta: Vec2,
 }
 
-/// Unit of scroll
+/// The scroll unit.
+///
+/// Describes how a value of a [`MouseWheel`](crate::mouse::MouseWheel) event has to be interpreted.
+///
+/// The value of the event can either be interpreted as the amount of lines or the amount of pixels
+/// to scroll.
 #[derive(Debug, Clone, Copy)]
 pub enum MouseScrollUnit {
+    /// The line scroll unit.
+    ///
+    /// The delta of the associated [`MouseWheel`](crate::mouse::MouseWheel) event corresponds
+    /// to the amount of lines or rows to scroll.
     Line,
+    /// The pixel scroll unit.
+    ///
+    /// The delta of the associated [`MouseWheel`](crate::mouse::MouseWheel) event corresponds
+    /// to the amount of pixels to scroll.
     Pixel,
 }
 
-/// A mouse scroll wheel event, where x represents horizontal scroll and y represents vertical
-/// scroll.
+/// A mouse wheel event.
+///
+/// This event is the translated version of the `WindowEvent::MouseWheel` from the `winit` crate.
 #[derive(Debug, Clone)]
 pub struct MouseWheel {
+    /// The mouse scroll unit.
     pub unit: MouseScrollUnit,
+    /// The horizontal scroll value.
     pub x: f32,
+    /// The vertical scroll value.
     pub y: f32,
 }
 
-/// Updates the `Input<MouseButton>` resource with the latest `MouseButtonInput` events
+/// Updates the [`Input<MouseButton>`] resource with the latest [`MouseButtonInput`] events.
+///
+/// ## Differences
+///
+/// The main difference between the [`MouseButtonInput`] event and the [`Input<MouseButton>`] resource is that
+/// the latter has convenient functions like [`Input::pressed`], [`Input::just_pressed`] and [`Input::just_released`].
 pub fn mouse_button_input_system(
     mut mouse_button_input: ResMut<Input<MouseButton>>,
     mut mouse_button_input_events: EventReader<MouseButtonInput>,