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

@@ -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.

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>,

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,

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,
 }
 

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,

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,