Improve docs

egui/src/containers/mod.rs

@@ -1,4 +1,4 @@
-//! Containers are pieces of the UI which wraps other pieces of UI. Examples: [`Window`], [`ScrollArea`], [`Resize`], etc.
+//! Containers are pieces of the UI which wraps other pieces of UI. Examples: [`Window`], [`ScrollArea`], [`Resize`], [`SidePanel`], etc.
 //!
 //! For instance, a [`Frame`] adds a frame and background to some contained UI.
 
@@ -6,7 +6,7 @@ pub(crate) mod area;
 pub(crate) mod collapsing_header;
 mod combo_box;
 pub(crate) mod frame;
-pub(crate) mod panel;
+pub mod panel;
 pub mod popup;
 pub(crate) mod resize;
 pub(crate) mod scroll_area;

egui/src/containers/panel.rs

@@ -1,12 +1,17 @@
-//! Panels are fixed [`Ui`] regions.
+//! Panels are [`Ui`] regions taking up e.g. the left side of a [`Ui`] or screen.
 //!
-//! Together with [`Window`] and [`Area`]:s they are
+//! Panels can either be a child of a [`Ui`] (taking up a portion of the parent)
+//! or be top-level (taking up a portion of the whole screen).
+//!
+//! Together with [`Window`] and [`Area`]:s, top-level panels are
 //! the only places where you can put you widgets.
 //!
 //! The order in which you add panels matter!
 //! The first panel you add will always be the outermost, and the last you add will always be the innermost.
 //!
-//! Always add any [`CentralPanel`] and [`Window`]:s last.
+//! Always add any [`CentralPanel`] last.
+//!
+//! Add your [`Window`]:s after any top-level panels.
 
 use std::ops::RangeInclusive;
 
@@ -50,12 +55,12 @@ impl Side {
     }
 }
 
-/// A panel that covers the entire left or right side of the screen.
+/// A panel that covers the entire left or right side of a [`Ui`] or screen.
 ///
 /// The order in which you add panels matter!
 /// The first panel you add will always be the outermost, and the last you add will always be the innermost.
 ///
-/// Always add any [`CentralPanel`] and [`Window`]:s last.
+/// See the [module level docs](crate::containers::panel) for more details.
 ///
 /// ```
 /// # let mut ctx = egui::CtxRef::default();
@@ -137,6 +142,7 @@ impl SidePanel {
 }
 
 impl SidePanel {
+    /// Show the panel inside a `Ui`.
     pub fn show_inside<R>(
         self,
         ui: &mut Ui,
@@ -248,6 +254,7 @@ impl SidePanel {
         inner_response
     }
 
+    /// Show the panel at the top level.
     pub fn show<R>(
         self,
         ctx: &CtxRef,
@@ -306,12 +313,12 @@ impl TopBottomSide {
     }
 }
 
-/// A panel that covers the entire top or bottom of the screen.
+/// A panel that covers the entire top or bottom of a [`Ui`] or screen.
 ///
 /// The order in which you add panels matter!
 /// The first panel you add will always be the outermost, and the last you add will always be the innermost.
 ///
-/// Always add any [`CentralPanel`] and [`Window`]:s last.
+/// See the [module level docs](crate::containers::panel) for more details.
 ///
 /// ```
 /// # let mut ctx = egui::CtxRef::default();
@@ -394,6 +401,7 @@ impl TopBottomPanel {
 }
 
 impl TopBottomPanel {
+    /// Show the panel inside a `Ui`.
     pub fn show_inside<R>(
         self,
         ui: &mut Ui,
@@ -507,6 +515,7 @@ impl TopBottomPanel {
         inner_response
     }
 
+    /// Show the panel at the top level.
     pub fn show<R>(
         self,
         ctx: &CtxRef,
@@ -556,7 +565,10 @@ impl TopPanel {
 /// i.e. whatever area is left after adding other panels.
 ///
 /// `CentralPanel` must be added after all other panels.
-/// Any [`Window`]s and [`Area`]s will cover the `CentralPanel`.
+///
+/// NOTE: Any [`Window`]s and [`Area`]s will cover the top-level `CentralPanel`.
+///
+/// See the [module level docs](crate::containers::panel) for more details.
 ///
 /// ```
 /// # let mut ctx = egui::CtxRef::default();
@@ -581,6 +593,7 @@ impl CentralPanel {
 }
 
 impl CentralPanel {
+    /// Show the panel inside a `Ui`.
     pub fn show_inside<R>(
         self,
         ui: &mut Ui,
@@ -598,6 +611,7 @@ impl CentralPanel {
         })
     }
 
+    /// Show the panel at the top level.
     pub fn show<R>(
         self,
         ctx: &CtxRef,

egui/src/widgets/progress_bar.rs

@@ -24,7 +24,7 @@ impl ProgressBar {
         }
     }
 
-    /// The desired width of the bar. Will use all horizonal space if not set.
+    /// The desired width of the bar. Will use all horizontal space if not set.
     pub fn desired_width(mut self, desired_width: f32) -> Self {
         self.desired_width = Some(desired_width);
         self
@@ -44,7 +44,7 @@ impl ProgressBar {
     }
 
     /// Whether to display a loading animation when progress `< 1`.
-    /// Note that this require the UI to be redrawn.
+    /// Note that this will cause the UI to be redrawn.
     /// Defaults to `false`.
     pub fn animate(mut self, animate: bool) -> Self {
         self.animate = animate;
@@ -58,10 +58,14 @@ impl Widget for ProgressBar {
             progress,
             desired_width,
             text,
-            mut animate,
+            animate,
         } = self;
 
-        animate &= progress < 1.0;
+        let animate = animate && progress < 1.0;
+
+        if animate {
+            ui.ctx().request_repaint();
+        }
 
         let desired_width = desired_width.unwrap_or(ui.available_size_before_wrap().x);
         let height = ui.spacing().interact_size.y;
@@ -85,7 +89,6 @@ impl Widget for ProgressBar {
 
         let (dark, bright) = (0.7, 1.0);
         let color_factor = if animate {
-            ui.ctx().request_repaint();
             lerp(dark..=bright, ui.input().time.cos().abs())
         } else {
             bright

epi/src/lib.rs

@@ -237,7 +237,7 @@ impl<'a> Frame<'a> {
     }
 
     /// Signal the app to stop/exit/quit the app (only works for native apps, not web apps).
-    /// The framework will NOT quick immediately, but at the end of the this frame.
+    /// The framework will not quit immediately, but at the end of the this frame.
     pub fn quit(&mut self) {
         self.0.output.quit = true;
     }