From 37a7ee448a4b3474a990f4b4cb1fa189a814482a Mon Sep 17 00:00:00 2001
From: Josie Elliston <68207187+JosieElliston@users.noreply.github.com>
Date: Tue, 26 May 2026 06:53:55 -0700
Subject: [PATCH] Improve `UiBuilder` docs (#8132)

Previously, the doc for `Ui::scope_builder` read

> Create a child, add content to it, and then allocate only what was
used in the parent `Ui`.

which I understood as meaning that "only what was used in the parent
`UI`" would be allocated (in the child or parent), which makes no sense
(in either case).

I rewrote it and some related docs.

Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
---
 crates/egui/src/ui.rs         | 9 +++++++--
 crates/egui/src/ui_builder.rs | 4 +++-
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/crates/egui/src/ui.rs b/crates/egui/src/ui.rs
index 840682979..d6a390377 100644
--- a/crates/egui/src/ui.rs
+++ b/crates/egui/src/ui.rs
@@ -2180,11 +2180,16 @@ impl Ui {
     /// });
     /// # });
     /// ```
+    ///
+    /// See also [`Self::scope_builder`] for more options.
     pub fn scope<R>(&mut self, add_contents: impl FnOnce(&mut Ui) -> R) -> InnerResponse<R> {
         self.scope_dyn(UiBuilder::new(), Box::new(add_contents))
     }
 
-    /// Create a child, add content to it, and then allocate only what was used in the parent `Ui`.
+    /// Create a scoped child ui, inheriting properties from the parent as specified by the [`UiBuilder`].
+    /// In contrast to [`Self::new_child`], this allocates the space used by the child.
+    ///
+    /// See also [`Self::scope`] and [`Self::scope_dyn`].
     pub fn scope_builder<R>(
         &mut self,
         ui_builder: UiBuilder,
@@ -2193,7 +2198,7 @@ impl Ui {
         self.scope_dyn(ui_builder, Box::new(add_contents))
     }
 
-    /// Create a child, add content to it, and then allocate only what was used in the parent `Ui`.
+    /// [`Self::scope_builder`] but with dynamic dispatch.
     pub fn scope_dyn<'c, R>(
         &mut self,
         ui_builder: UiBuilder,
diff --git a/crates/egui/src/ui_builder.rs b/crates/egui/src/ui_builder.rs
index 893b34468..0900d0d06 100644
--- a/crates/egui/src/ui_builder.rs
+++ b/crates/egui/src/ui_builder.rs
@@ -7,11 +7,13 @@ use crate::{
     widget_style::{Classes, HasClasses},
 };
 
-/// Build a [`Ui`] as the child of another [`Ui`].
+/// The properties specified when creating a top-level or child [`Ui`].
 ///
 /// By default, everything is inherited from the parent,
 /// except for `max_rect` which by default is set to
 /// the parent [`Ui::available_rect_before_wrap`].
+///
+/// See also [`Ui::new`] and [`Ui::new_child`] for uses.
 #[must_use]
 #[derive(Clone, Default)]
 pub struct UiBuilder {