From fe2c13c7775de56572ff8216990d3dfd64ede9b7 Mon Sep 17 00:00:00 2001
From: Euclid Ye <euclid.ye@huawei.com>
Date: Thu, 17 Jul 2025 21:40:28 +0800
Subject: [PATCH] doc: Add doc for compositor/webview/embedder related to
 window/rect/inner_size/rendering_context (#38110)

Add docs before actually fixing #38089, #38090, #37978, #38093.

Testing: Just adding docs.

---------

Signed-off-by: Euclid Ye <euclid.ye@huawei.com>
---
 components/compositing/compositor.rs       | 2 +-
 components/compositing/webview_renderer.rs | 1 +
 components/servo/webview.rs                | 2 +-
 components/shared/embedder/lib.rs          | 7 ++++---
 ports/servoshell/desktop/headed_window.rs  | 2 ++
 ports/servoshell/desktop/window_trait.rs   | 1 +
 6 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/components/compositing/compositor.rs b/components/compositing/compositor.rs
index 8ac43391e86..5a422444493 100644
--- a/components/compositing/compositor.rs
+++ b/components/compositing/compositor.rs
@@ -150,7 +150,7 @@ pub struct IOCompositor {
     /// The webrender renderer.
     webrender: Option<webrender::Renderer>,
 
-    /// The surfman instance that webrender targets
+    /// The surfman instance that webrender targets, which is the viewport.
     rendering_context: Rc<dyn RenderingContext>,
 
     /// The number of frames pending to receive from WebRender.
diff --git a/components/compositing/webview_renderer.rs b/components/compositing/webview_renderer.rs
index 38f3195fdc6..f8e409b2942 100644
--- a/components/compositing/webview_renderer.rs
+++ b/components/compositing/webview_renderer.rs
@@ -76,6 +76,7 @@ pub(crate) struct WebViewRenderer {
     pub webview: Box<dyn WebViewTrait>,
     /// The root [`PipelineId`] of the currently displayed page in this WebView.
     pub root_pipeline_id: Option<PipelineId>,
+    /// The rectangle of the [`WebView`] in device pixels, which is the viewport.
     pub rect: DeviceRect,
     /// Tracks details about each active pipeline that the compositor knows about.
     pub pipelines: HashMap<PipelineId, PipelineDetails>,
diff --git a/components/servo/webview.rs b/components/servo/webview.rs
index 7ec4644fa67..b28354510a5 100644
--- a/components/servo/webview.rs
+++ b/components/servo/webview.rs
@@ -77,7 +77,7 @@ pub(crate) struct WebViewInner {
     pub(crate) delegate: Rc<dyn WebViewDelegate>,
     pub(crate) clipboard_delegate: Rc<dyn ClipboardDelegate>,
     javascript_evaluator: Rc<RefCell<JavaScriptEvaluator>>,
-
+    /// The rectangle of the [`WebView`] in device pixels, which is the viewport.
     rect: DeviceRect,
     hidpi_scale_factor: Scale<f32, DeviceIndependentPixel, DevicePixel>,
     load_status: LoadStatus,
diff --git a/components/shared/embedder/lib.rs b/components/shared/embedder/lib.rs
index 51de4e580fb..10878cc4c69 100644
--- a/components/shared/embedder/lib.rs
+++ b/components/shared/embedder/lib.rs
@@ -796,9 +796,10 @@ pub struct ScreenGeometry {
     /// toolbars, docks, and interface elements. This will be converted to
     /// CSS pixels based on the pixel scaling of the `WebView`.
     pub available_size: DeviceIntSize,
-    /// The rectangle the `WebView`'s containing window in device pixels for the purposes of the
-    /// `window.screenLeft` and similar APIs. This will be converted to CSS pixels based
-    /// on the pixel scaling of the `WebView`.
+    /// The rectangle the `WebView`'s containing window (including OS decorations)
+    /// in device pixels for the purposes of the
+    /// `window.screenLeft`, `window.outerHeight` and similar APIs.
+    /// This will be converted to CSS pixels based on the pixel scaling of the `WebView`.
     pub window_rect: DeviceIntRect,
 }
 
diff --git a/ports/servoshell/desktop/headed_window.rs b/ports/servoshell/desktop/headed_window.rs
index 739fd9fdc75..ac55a9eea84 100644
--- a/ports/servoshell/desktop/headed_window.rs
+++ b/ports/servoshell/desktop/headed_window.rs
@@ -55,6 +55,8 @@ use crate::prefs::ServoShellPreferences;
 
 pub struct Window {
     screen_size: Size2D<u32, DeviceIndependentPixel>,
+    /// The inner size of the window in physical pixels which excludes OS decorations.
+    /// It equals viewport size + (0, toolbar height).
     inner_size: Cell<PhysicalSize<u32>>,
     toolbar_height: Cell<Length<f32, DeviceIndependentPixel>>,
     monitor: winit::monitor::MonitorHandle,
diff --git a/ports/servoshell/desktop/window_trait.rs b/ports/servoshell/desktop/window_trait.rs
index 2c9f508b728..62e81b1ee73 100644
--- a/ports/servoshell/desktop/window_trait.rs
+++ b/ports/servoshell/desktop/window_trait.rs
@@ -40,6 +40,7 @@ pub trait WindowPortsMethods {
     fn winit_window(&self) -> Option<&winit::window::Window>;
     fn toolbar_height(&self) -> Length<f32, DeviceIndependentPixel>;
     fn set_toolbar_height(&self, height: Length<f32, DeviceIndependentPixel>);
+    /// This returns [`RenderingContext`] matching the viewport.
     fn rendering_context(&self) -> Rc<dyn RenderingContext>;
     fn show_ime(
         &self,