From b393bdcb74b6d8f83189e55a4f4c52b72080e708 Mon Sep 17 00:00:00 2001
From: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
Date: Wed, 31 Mar 2021 21:49:24 +0200
Subject: [PATCH] Improve documentation of `ui.add_sized`

---
 egui/src/lib.rs |  9 +++++++++
 egui/src/ui.rs  | 19 ++++++++++++++++---
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/egui/src/lib.rs b/egui/src/lib.rs
index 4e51cb9b..2f1af240 100644
--- a/egui/src/lib.rs
+++ b/egui/src/lib.rs
@@ -201,6 +201,15 @@
 //! }
 //! ```
 //!
+//! ## Sizes
+//! You can control the size of widgets using [`Ui::add_sized`].
+//!
+//! ```
+//! # let ui = &mut egui::Ui::__test();
+//! # let mut my_value = 0.0_f32;
+//! ui.add_sized([40.0, 20.0], egui::DragValue::new(&mut my_value));
+//! ```
+//!
 //! ## Code snippets
 //!
 //! ```
diff --git a/egui/src/ui.rs b/egui/src/ui.rs
index 7a516131..314ece93 100644
--- a/egui/src/ui.rs
+++ b/egui/src/ui.rs
@@ -781,6 +781,8 @@ impl Ui {
     /// The returned [`Response`] can be used to check for interactions,
     /// as well as adding tooltips using [`Response::on_hover_text`].
     ///
+    /// See also [`Self::add_sized`] and [`Self::put`].
+    ///
     /// ```
     /// # let mut ui = egui::Ui::__test();
     /// # let mut my_value = 42;
@@ -791,15 +793,26 @@ impl Ui {
         widget.ui(self)
     }
 
-    /// Add a [`Widget`] to this `Ui` with a given max size.
-    pub fn add_sized(&mut self, max_size: Vec2, widget: impl Widget) -> Response {
-        self.allocate_ui(max_size, |ui| {
+    /// Add a [`Widget`] to this `Ui` with a given size.
+    /// The widget will attempt to fit within the given size, but some widgets may overflow.
+    ///
+    /// See also [`Self::add`] and [`Self::put`].
+    ///
+    /// ```
+    /// # let mut ui = egui::Ui::__test();
+    /// # let mut my_value = 42;
+    /// ui.add_sized([40.0, 20.0], egui::DragValue::new(&mut my_value));
+    /// ```
+    pub fn add_sized(&mut self, max_size: impl Into<Vec2>, widget: impl Widget) -> Response {
+        self.allocate_ui(max_size.into(), |ui| {
             ui.centered_and_justified(|ui| ui.add(widget)).inner
         })
         .inner
     }
 
     /// Add a [`Widget`] to this `Ui` at a specific location (manual layout).
+    ///
+    /// See also [`Self::add`] and [`Self::add_sized`].
     pub fn put(&mut self, max_rect: Rect, widget: impl Widget) -> Response {
         self.allocate_ui_at_rect(max_rect, |ui| {
             ui.centered_and_justified(|ui| ui.add(widget)).inner