From addb0703b10a477616729075d633079490bdfbda Mon Sep 17 00:00:00 2001
From: Reinis Mazeiks <reinis.mazeiks@gmail.com>
Date: Thu, 12 May 2022 11:12:34 +0300
Subject: [PATCH] Write docs for wheel events

---
 packages/html/src/events.rs   | 3 +++
 packages/html/src/geometry.rs | 9 +++++++++
 2 files changed, 12 insertions(+)

diff --git a/packages/html/src/events.rs b/packages/html/src/events.rs
index 38ae75407..4cb7c6fb1 100644
--- a/packages/html/src/events.rs
+++ b/packages/html/src/events.rs
@@ -755,6 +755,7 @@ pub mod on {
     }
 
     impl WheelData {
+        /// Construct a new WheelData with the specified wheel movement delta
         pub fn new(delta: WheelDelta) -> Self {
             let (delta_mode, vector) = match delta {
                 WheelDelta::Pixels(v) => (0, v.cast_unit::<UnknownUnit>()),
@@ -771,6 +772,7 @@ pub mod on {
             }
         }
 
+        /// Construct from the attributes of the web wheel event
         pub fn from_web_attributes(
             delta_mode: u32,
             delta_x: f64,
@@ -786,6 +788,7 @@ pub mod on {
             }
         }
 
+        /// The amount of wheel movement
         #[allow(deprecated)]
         pub fn delta(&self) -> WheelDelta {
             let x = self.delta_x;
diff --git a/packages/html/src/geometry.rs b/packages/html/src/geometry.rs
index 97ab068d3..027922a85 100644
--- a/packages/html/src/geometry.rs
+++ b/packages/html/src/geometry.rs
@@ -48,6 +48,7 @@ pub type PagesVector = Vector3D<f64, Pages>;
 ///
 /// This may be expressed in Pixels, Lines or Pages
 #[derive(Copy, Clone, Debug)]
+#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
 pub enum WheelDelta {
     /// Movement in Pixels
     Pixels(PixelsVector),
@@ -73,10 +74,18 @@ impl WheelDelta {
         WheelDelta::Pages(PagesVector::new(x, y, z))
     }
 
+    /// Returns true iff there is no wheel movement
+    ///
+    /// i.e. the x, y and z delta is zero (disregards units)
     pub fn is_zero(&self) -> bool {
         self.strip_units() == Vector3D::new(0., 0., 0.)
     }
 
+    /// A Vector3D proportional to the amount scrolled
+    ///
+    /// Note that this disregards the 3 possible units: this could be expressed in terms of pixels, lines, or pages.
+    ///
+    /// In most cases, to properly handle scrolling, you should handle all 3 possible enum variants instead of stripping units. Otherwise, if you assume that the units will always be pixels, the user may experience some unexpectedly slow scrolling if their mouse/OS sends values expressed in lines or pages.
     pub fn strip_units(&self) -> Vector3D<f64, UnknownUnit> {
         match self {
             WheelDelta::Pixels(v) => v.cast_unit(),