Fix documentation

examples/window.rs

@@ -740,7 +740,7 @@ impl WindowState {
                 self.resize(new_surface_size);
             }
         } else {
-            info!("Request inner size is asynchronous");
+            info!("Requesting surface size is asynchronous");
         }
     }
 

src/changelog/unreleased.md

@@ -105,6 +105,23 @@ changelog entry.
 - On iOS, no longer act as-if the application successfully open all URLs. Override
   `application:didFinishLaunchingWithOptions:` and provide the desired behaviour yourself.
 - On X11, remove our dependency on libXcursor. (#3749)
+- Renamed the following APIs to make it clearer that the sizes apply to the underlying surface:
+  - `WindowEvent::Resized` to `SurfaceResized`.
+  - `InnerSizeWriter` to `SurfaceSizeWriter`.
+  - `WindowAttributes.inner_size` to `surface_size`.
+  - `WindowAttributes.min_inner_size` to `min_surface_size`.
+  - `WindowAttributes.max_inner_size` to `max_surface_size`.
+  - `WindowAttributes.resize_increments` to `surface_resize_increments`.
+  - `WindowAttributes::with_inner_size` to `with_surface_size`.
+  - `WindowAttributes::with_min_inner_size` to `with_min_surface_size`.
+  - `WindowAttributes::with_max_inner_size` to `with_max_surface_size`.
+  - `WindowAttributes::with_resize_increments` to `with_surface_resize_increments`.
+  - `Window::inner_size` to `surface_size`.
+  - `Window::request_inner_size` to `request_surface_size`.
+  - `Window::set_min_inner_size` to `set_min_surface_size`.
+  - `Window::set_max_inner_size` to `set_max_surface_size`.
+
+  To migrate, you can probably just replace all instances of `inner_size` with `surface_size` in your codebase.
 
 ### Removed
 

src/event.rs

@@ -148,7 +148,12 @@ pub enum WindowEvent {
     /// [`request_activation_token`]: crate::platform::startup_notify::WindowExtStartupNotify::request_activation_token
     ActivationTokenDone { serial: AsyncRequestSerial, token: ActivationToken },
 
-    /// The size of the window has changed. Contains the client area's new dimensions.
+    /// The size of the window's surface has changed.
+    ///
+    /// Contains the new dimensions of the surface (can also be retrieved with
+    /// [`Window::surface_size`]).
+    ///
+    /// [`Window::surface_size`]: crate::window::Window::surface_size
     SurfaceResized(PhysicalSize<u32>),
 
     /// The position of the window has changed. Contains the window's new position.
@@ -366,7 +371,7 @@ pub enum WindowEvent {
     /// For more information about DPI in general, see the [`dpi`] crate.
     ScaleFactorChanged {
         scale_factor: f64,
-        /// Handle to update inner size during scale changes.
+        /// Handle to update surface size during scale changes.
         ///
         /// See [`SurfaceSizeWriter`] docs for more details.
         surface_size_writer: SurfaceSizeWriter,
@@ -995,8 +1000,7 @@ pub enum MouseScrollDelta {
     PixelDelta(PhysicalPosition<f64>),
 }
 
-/// Handle to synchronously change the size of the window from the
-/// [`WindowEvent`].
+/// Handle to synchronously change the size of the window from the [`WindowEvent`].
 #[derive(Debug, Clone)]
 pub struct SurfaceSizeWriter {
     pub(crate) new_surface_size: Weak<Mutex<PhysicalSize<u32>>>,
@@ -1008,7 +1012,7 @@ impl SurfaceSizeWriter {
         Self { new_surface_size }
     }
 
-    /// Try to request inner size which will be set synchronously on the window.
+    /// Try to request surface size which will be set synchronously on the window.
     pub fn request_surface_size(
         &mut self,
         new_surface_size: PhysicalSize<u32>,

src/platform_impl/linux/wayland/window/mod.rs

@@ -348,7 +348,7 @@ impl CoreWindow for Window {
         self.request_redraw();
     }
 
-    /// Set the maximum inner size for the window.
+    /// Set the maximum surface size for the window.
     #[inline]
     fn set_max_surface_size(&self, max_size: Option<Size>) {
         let scale_factor = self.scale_factor();

src/platform_impl/linux/wayland/window/state.rs

@@ -46,7 +46,7 @@ pub type WinitFrame = sctk_adwaita::AdwaitaFrame<WinitState>;
 #[cfg(not(feature = "sctk-adwaita"))]
 pub type WinitFrame = sctk::shell::xdg::fallback_frame::FallbackFrame<WinitState>;
 
-// Minimum window inner size.
+// Minimum window surface size.
 const MIN_WINDOW_SIZE: LogicalSize<u32> = LogicalSize::new(2, 1);
 
 /// The state of the window which is being updated from the [`WinitState`].
@@ -112,7 +112,7 @@ pub struct WindowState {
     /// The text inputs observed on the window.
     text_inputs: Vec<ZwpTextInputV3>,
 
-    /// The inner size of the window, as in without client side decorations.
+    /// The surface size of the window, as in without client side decorations.
     size: LogicalSize<u32>,
 
     /// Whether the CSD fail to create, so we don't try to create them on each iteration.
@@ -361,7 +361,7 @@ impl WindowState {
         }
     }
 
-    /// Compute the bounds for the inner size of the surface.
+    /// Compute the bounds for the surface size of the surface.
     fn surface_size_bounds(
         &self,
         configure: &WindowConfigure,
@@ -636,7 +636,7 @@ impl WindowState {
         logical_to_physical_rounded(self.surface_size(), self.scale_factor())
     }
 
-    /// Resize the window to the new inner size.
+    /// Resize the window to the new surface size.
     fn resize(&mut self, surface_size: LogicalSize<u32>) {
         self.size = surface_size;
 
@@ -673,7 +673,7 @@ impl WindowState {
 
         // Update the target viewport, this is used if and only if fractional scaling is in use.
         if let Some(viewport) = self.viewport.as_ref() {
-            // Set inner size without the borders.
+            // Set surface size without the borders.
             viewport.set_destination(self.size.width as _, self.size.height as _);
         }
     }

src/platform_impl/windows/event_loop.rs

@@ -2131,7 +2131,7 @@ unsafe fn public_window_callback_inner(
             // New size as suggested by Windows.
             let suggested_rect = unsafe { *(lparam as *const RECT) };
 
-            // The window rect provided is the window's outer size, not it's inner size. However,
+            // The window rect provided is the window's outer size, not it's surface size. However,
             // win32 doesn't provide an `UnadjustWindowRectEx` function to get the client rect from
             // the outer rect, so we instead adjust the window rect to get the decoration margins
             // and remove them from the outer size.

src/window.rs

@@ -137,7 +137,7 @@ impl WindowAttributes {
         self.parent_window.as_ref().map(|handle| &handle.0)
     }
 
-    /// Requests the window to be of specific dimensions.
+    /// Requests the surface to be of specific dimensions.
     ///
     /// If this is not set, some platform-specific dimensions will be used.
     ///
@@ -148,10 +148,9 @@ impl WindowAttributes {
         self
     }
 
-    /// Sets the minimum dimensions a window can have.
+    /// Sets the minimum dimensions the surface can have.
     ///
-    /// If this is not set, the window will have no minimum dimensions (aside
-    /// from reserved).
+    /// If this is not set, the surface will have no minimum dimensions (aside from reserved).
     ///
     /// See [`Window::set_min_surface_size`] for details.
     #[inline]
@@ -160,9 +159,9 @@ impl WindowAttributes {
         self
     }
 
-    /// Sets the maximum dimensions a window can have.
+    /// Sets the maximum dimensions the surface can have.
     ///
-    /// If this is not set, the window will have no maximum or will be set to
+    /// If this is not set, the surface will have no maximum, or the maximum will be restricted to
     /// the primary monitor's dimensions by the platform.
     ///
     /// See [`Window::set_max_surface_size`] for details.
@@ -653,9 +652,9 @@ pub trait Window: AsAny + Send + Sync {
     /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform
     fn set_outer_position(&self, position: Position);
 
-    /// Returns the physical size of the window's client area.
+    /// Returns the size of the window's render-able surface.
     ///
-    /// The client area is the content of the window, excluding the title bar and borders.
+    /// This is the dimensions you should pass to things like Wgpu or Glutin when configuring.
     ///
     /// ## Platform-specific
     ///
@@ -667,14 +666,14 @@ pub trait Window: AsAny + Send + Sync {
     /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform
     fn surface_size(&self) -> PhysicalSize<u32>;
 
-    /// Request the new size for the window.
+    /// Request the new size for the surface.
     ///
     /// On platforms where the size is entirely controlled by the user the
     /// applied size will be returned immediately, resize event in such case
     /// may not be generated.
     ///
-    /// On platforms where resizing is disallowed by the windowing system, the current
-    /// inner size is returned immediately, and the user one is ignored.
+    /// On platforms where resizing is disallowed by the windowing system, the current surface size
+    /// is returned immediately, and the user one is ignored.
     ///
     /// When `None` is returned, it means that the request went to the display system,
     /// and the actual size will be delivered later with the [`WindowEvent::SurfaceResized`].
@@ -704,10 +703,10 @@ pub trait Window: AsAny + Send + Sync {
     #[must_use]
     fn request_surface_size(&self, size: Size) -> Option<PhysicalSize<u32>>;
 
-    /// Returns the physical size of the entire window.
+    /// Returns the size of the entire window.
     ///
-    /// These dimensions include the title bar and borders. If you don't want that (and you usually
-    /// don't), use [`Window::surface_size`] instead.
+    /// These dimensions include window decorations like the title bar and borders. If you don't
+    /// want that (and you usually don't), use [`Window::surface_size`] instead.
     ///
     /// ## Platform-specific
     ///
@@ -716,7 +715,7 @@ pub trait Window: AsAny + Send + Sync {
     ///   [`Window::surface_size`]._
     fn outer_size(&self) -> PhysicalSize<u32>;
 
-    /// Sets a minimum dimension size for the window.
+    /// Sets a minimum dimensions of the window's surface.
     ///
     /// ```no_run
     /// # use winit::dpi::{LogicalSize, PhysicalSize};
@@ -735,7 +734,7 @@ pub trait Window: AsAny + Send + Sync {
     /// - **iOS / Android / Orbital:** Unsupported.
     fn set_min_surface_size(&self, min_size: Option<Size>);
 
-    /// Sets a maximum dimension size for the window.
+    /// Sets a maximum dimensions of the window's surface.
     ///
     /// ```no_run
     /// # use winit::dpi::{LogicalSize, PhysicalSize};
@@ -754,17 +753,17 @@ pub trait Window: AsAny + Send + Sync {
     /// - **iOS / Android / Orbital:** Unsupported.
     fn set_max_surface_size(&self, max_size: Option<Size>);
 
-    /// Returns window resize increments if any were set.
+    /// Returns surface resize increments if any were set.
     ///
     /// ## Platform-specific
     ///
     /// - **iOS / Android / Web / Wayland / Orbital:** Always returns [`None`].
     fn surface_resize_increments(&self) -> Option<PhysicalSize<u32>>;
 
-    /// Sets window resize increments.
+    /// Sets resize increments of the surface.
     ///
-    /// This is a niche constraint hint usually employed by terminal emulators
-    /// and other apps that need "blocky" resizes.
+    /// This is a niche constraint hint usually employed by terminal emulators and other such apps
+    /// that need "blocky" resizes.
     ///
     /// ## Platform-specific
     ///