Improve Web specific documentation for various APIs (#2941)

Co-authored-by: Kirill Chibisov <contact@kchibisov.com>

src/event.rs

@@ -84,7 +84,7 @@ pub enum Event<'a, T: 'static> {
     ///
     /// Not all platforms support the notion of suspending applications, and there may be no
     /// technical way to guarantee being able to emit a `Suspended` event if the OS has
-    /// no formal application lifecycle (currently only Android and iOS do). For this reason,
+    /// no formal application lifecycle (currently only Android, iOS, and Web do). For this reason,
     /// Winit does not currently try to emit pseudo `Suspended` events before the application
     /// quits on platforms without an application lifecycle.
     ///
@@ -430,6 +430,14 @@ pub enum WindowEvent<'a> {
     Ime(Ime),
 
     /// The cursor has moved on the window.
+    ///
+    /// ## Platform-specific
+    ///
+    /// - **Web:** Doesn't take into account CSS [`border`], [`padding`], or [`transform`].
+    ///
+    /// [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border
+    /// [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding
+    /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform
     CursorMoved {
         device_id: DeviceId,
 
@@ -440,9 +448,25 @@ pub enum WindowEvent<'a> {
     },
 
     /// The cursor has entered the window.
+    ///
+    /// ## Platform-specific
+    ///
+    /// - **Web:** Doesn't take into account CSS [`border`], [`padding`], or [`transform`].
+    ///
+    /// [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border
+    /// [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding
+    /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform
     CursorEntered { device_id: DeviceId },
 
     /// The cursor has left the window.
+    ///
+    /// ## Platform-specific
+    ///
+    /// - **Web:** Doesn't take into account CSS [`border`], [`padding`], or [`transform`].
+    ///
+    /// [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border
+    /// [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding
+    /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform
     CursorLeft { device_id: DeviceId },
 
     /// A mouse wheel movement or touchpad scroll occurred.
@@ -528,7 +552,12 @@ pub enum WindowEvent<'a> {
     ///
     /// ## Platform-specific
     ///
+    /// - **Web:** Doesn't take into account CSS [`border`], [`padding`], or [`transform`].
     /// - **macOS:** Unsupported.
+    ///
+    /// [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border
+    /// [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding
+    /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform
     Touch(Touch),
 
     /// The window's scale factor has changed.
@@ -566,11 +595,12 @@ pub enum WindowEvent<'a> {
     ///
     /// Platform-specific behavior:
     ///
-    /// - **Web:** Doesn't take into account CSS [`border`] or [`padding`].
+    /// - **Web:** Doesn't take into account CSS [`border`], [`padding`], or [`transform`].
     /// - **iOS / Android / Wayland / Windows / Orbital:** Unsupported.
     ///
     /// [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border
     /// [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding
+    /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform
     Occluded(bool),
 }
 
@@ -1142,7 +1172,12 @@ pub enum TouchPhase {
 ///
 /// ## Platform-specific
 ///
+/// - **Web:** Doesn't take into account CSS [`border`], [`padding`], or [`transform`].
 /// - **macOS:** Unsupported.
+///
+/// [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border
+/// [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding
+/// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Touch {
     pub device_id: DeviceId,
@@ -1153,7 +1188,7 @@ pub struct Touch {
     ///
     /// ## Platform-specific
     ///
-    /// - Only available on **iOS** 9.0+ and **Windows** 8+.
+    /// - Only available on **iOS** 9.0+, **Windows** 8+, and **Web**.
     pub force: Option<Force>,
     /// Unique identifier of a finger.
     pub id: u64,

src/platform/web.rs

@@ -2,6 +2,28 @@
 //! allow end users to determine how the page should be laid out. Use the [`WindowExtWebSys`] trait
 //! to retrieve the canvas from the Window. Alternatively, use the [`WindowBuilderExtWebSys`] trait
 //! to provide your own canvas.
+//!
+//! It is recommended **not** to apply certain CSS properties to the canvas:
+//! - [`transform`]
+//! - [`border`]
+//! - [`padding`]
+//!
+//! The following APIs can't take them into account and will therefore provide inaccurate results:
+//! - [`WindowEvent::Resized`] and [`Window::(set_)inner_size()`]
+//! - [`WindowEvent::Occluded`]
+//! - [`WindowEvent::CursorMoved`], [`WindowEvent::CursorEntered`], [`WindowEvent::CursorLeft`],
+//!   and [`WindowEvent::Touch`].
+//!
+//! [`WindowEvent::Resized`]: crate::event::WindowEvent::Resized
+//! [`Window::(set_)inner_size()`]: crate::window::Window::inner_size()
+//! [`WindowEvent::Occluded`]: crate::event::WindowEvent::Occluded
+//! [`WindowEvent::CursorMoved`]: crate::event::WindowEvent::CursorMoved
+//! [`WindowEvent::CursorEntered`]: crate::event::WindowEvent::CursorEntered
+//! [`WindowEvent::CursorLeft`]: crate::event::WindowEvent::CursorLeft
+//! [`WindowEvent::Touch`]: crate::event::WindowEvent::Touch
+//! [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform
+//! [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border
+//! [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding
 
 use crate::event::Event;
 use crate::event_loop::ControlFlow;

src/window.rs

@@ -644,9 +644,10 @@ impl Window {
     ///
     /// - **iOS:** Can only be called on the main thread. Returns the `PhysicalSize` of the window's
     ///   [safe area] in screen space coordinates.
-    /// - **Web:** Returns the size of the canvas element.
+    /// - **Web:** Returns the size of the canvas element. Doesn't account for CSS [`transform`].
     ///
     /// [safe area]: https://developer.apple.com/documentation/uikit/uiview/2891103-safeareainsets?language=objc
+    /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform
     #[inline]
     pub fn inner_size(&self) -> PhysicalSize<u32> {
         self.window.inner_size()
@@ -683,9 +684,10 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// - **Web:** Sets the size of the canvas element.
+    /// - **Web:** Sets the size of the canvas element. Doesn't account for CSS [`transform`].
     ///
-    /// [`WindowEvent::Resized`]: crate::event::WindowEvent::Resized.
+    /// [`WindowEvent::Resized`]: crate::event::WindowEvent::Resized
+    /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform
     #[inline]
     #[must_use]
     pub fn request_inner_size<S: Into<Size>>(&self, size: S) -> Option<PhysicalSize<u32>> {