Improve Web specific documentation for various APIs

Co-Authored-By: Kirill Chibisov <[email protected]>
rust-windowing · Jul 9, 2023 · 4fe18a4 · 4fe18a4
1 parent bd890e6
commit 4fe18a4
Show file tree

Hide file tree

Showing 3 changed files with 20 additions and 4 deletions.
diff --git a/src/event.rs b/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.
     ///
@@ -1148,7 +1148,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,

diff --git a/src/platform/web.rs b/src/platform/web.rs
@@ -2,6 +2,19 @@
 //! 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`] - which causes [`WindowEvent::Resized`] and [`Window::(set_)inner_size()`] to
+//!   be inaccurate.
+//! - [`border`] - which causes [`WindowEvent::Occluded`] to be inaccurate.
+//! - [`padding`] - which causes [`WindowEvent::Occluded`] to be inaccurate.
+//!
+//! [`WindowEvent::Resized`]: crate::event::WindowEvent::Resized
+//! [`Window::(set_)inner_size()`]: crate::window::Window::inner_size()
+//! [`WindowEvent::Occluded`]: crate::event::WindowEvent::Occluded
+//! [`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;

diff --git a/src/window.rs b/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()
@@ -673,7 +674,9 @@ impl Window {
     /// ## Platform-specific
     ///
     /// - **iOS / Android:** Unsupported.
-    /// - **Web:** Sets the size of the canvas element.
+    /// - **Web:** Sets the size of the canvas element. Doesn't account for CSS [`transform`].
+    ///
+    /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform
     #[inline]
     pub fn set_inner_size<S: Into<Size>>(&self, size: S) {
         self.window.set_inner_size(size.into())