[doc] improve Egui documentation

egui/src/containers.rs

@@ -1,11 +1,11 @@
-pub mod area;
-pub mod collapsing_header;
-pub mod frame;
-pub mod menu;
-pub mod popup;
-pub mod resize;
-pub mod scroll_area;
-pub mod window;
+pub(crate) mod area;
+pub(crate) mod collapsing_header;
+pub(crate) mod frame;
+pub(crate) mod menu;
+pub(crate) mod popup;
+pub(crate) mod resize;
+pub(crate) mod scroll_area;
+pub(crate) mod window;
 
 pub use {
     area::Area, collapsing_header::CollapsingHeader, frame::Frame, popup::*, resize::Resize,

egui/src/containers/window.rs

@@ -1,6 +1,6 @@
 use std::sync::Arc;
 
-use crate::{widgets::*, *};
+use crate::{paint::*, widgets::*, *};
 
 use super::*;
 

egui/src/demos/app.rs

@@ -1,6 +1,6 @@
 use std::sync::Arc;
 
-use crate::{color::*, containers::*, demos::FractalClock, widgets::*, *};
+use crate::{color::*, containers::*, demos::FractalClock, paint::*, widgets::*, *};
 
 // ----------------------------------------------------------------------------
 
@@ -298,15 +298,9 @@ impl Widgets {
             });
 
         ui.horizontal(|ui| {
-            if ui.add(radio(self.radio == 0, "First")).clicked {
-                self.radio = 0;
-            }
-            if ui.add(radio(self.radio == 1, "Second")).clicked {
-                self.radio = 1;
-            }
-            if ui.add(radio(self.radio == 2, "Final")).clicked {
-                self.radio = 2;
-            }
+            ui.radio_value("First", &mut self.radio, 0);
+            ui.radio_value("Second", &mut self.radio, 1);
+            ui.radio_value("Final", &mut self.radio, 2);
         });
 
         ui.add(Checkbox::new(&mut self.button_enabled, "Button enabled"));

egui/src/demos/fractal_clock.rs

@@ -1,6 +1,6 @@
 use std::sync::Arc;
 
-use crate::{containers::*, widgets::*, *};
+use crate::{containers::*, paint::PaintCmd, widgets::*, *};
 
 #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "with_serde", serde(default))]

egui/src/id.rs

@@ -1,34 +1,32 @@
-//! Egui tracks widgets frame-to-frame using `Id`s.
-//!
-//! For instance, if you start dragging a slider one frame, egui stores
-//! the sliders `Id` as the current active id so that next frame when
-//! you move the mouse the same slider changes, even if the mouse has
-//! moved outside the slider.
-//!
-//! For some widgets `Id`s are also used to persist some state about the
-//! widgets, such as Window position or wether not a collapsing header region is open.
-//!
-//! This implicates that the `Id`s must be unqiue.
-//!
-//! For simple things like sliders and buttons that don't have any memory and
-//! doesn't move we can use the location of the widget as a source of identity.
-//! For instance, a slider only needs a unique and persistent ID while you are
-//! dragging the slider. As long as it is still while moving, that is fine.
-//!
-//! For things that need to persist state even after moving (windows, collapsing headers)
-//! the location of the widgets is obviously not good enough. For instance,
-//! a collapsing region needs to remember wether or not it is open even
-//! if the layout next frame is different and the collapsing is not lower down
-//! on the screen.
-//!
-//! Then there are widgets that need no identifiers at all, like labels,
-//! because they have no state nor are interacted with.
-//!
-//! So we have two type of Ids: `PositionId` and `UniqueId`.
-//! TODO: have separate types for `PositionId` and `UniqueId`.
+// TODO: have separate types `PositionId` and `UniqueId`. ?
 
 use std::hash::Hash;
 
+/// Egui tracks widgets frame-to-frame using `Id`s.
+///
+/// For instance, if you start dragging a slider one frame, egui stores
+/// the sliders `Id` as the current active id so that next frame when
+/// you move the mouse the same slider changes, even if the mouse has
+/// moved outside the slider.
+///
+/// For some widgets `Id`s are also used to persist some state about the
+/// widgets, such as Window position or wether not a collapsing header region is open.
+///
+/// This implies that the `Id`s must be unqiue.
+///
+/// For simple things like sliders and buttons that don't have any memory and
+/// doesn't move we can use the location of the widget as a source of identity.
+/// For instance, a slider only needs a unique and persistent ID while you are
+/// dragging the slider. As long as it is still while moving, that is fine.
+///
+/// For things that need to persist state even after moving (windows, collapsing headers)
+/// the location of the widgets is obviously not good enough. For instance,
+/// a collapsing region needs to remember wether or not it is open even
+/// if the layout next frame is different and the collapsing is not lower down
+/// on the screen.
+///
+/// Then there are widgets that need no identifiers at all, like labels,
+/// because they have no state nor are interacted with.
 #[derive(Clone, Copy, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))]
 pub struct Id(u64);

egui/src/layers.rs

@@ -37,7 +37,7 @@ impl Layer {
 /// Each `PaintCmd` is paired with a clip rectangle.
 type PaintList = Vec<(Rect, PaintCmd)>;
 
-/// TODO: improve this
+// TODO: improve this
 #[derive(Clone, Default)]
 pub struct GraphicLayers(AHashMap<Layer, PaintList>);
 

egui/src/layout.rs

@@ -39,7 +39,7 @@ impl Default for Align {
 
 /// Used e.g. to anchor a piece of text to a part of the rectangle.
 /// Give a position within the rect, specified by the aligns
-pub fn align_rect(rect: Rect, align: (Align, Align)) -> Rect {
+pub(crate) fn align_rect(rect: Rect, align: (Align, Align)) -> Rect {
     let x = match align.0 {
         Align::Min => rect.left(),
         Align::Center => rect.left() - 0.5 * rect.width(),
@@ -55,6 +55,7 @@ pub fn align_rect(rect: Rect, align: (Align, Align)) -> Rect {
 
 // ----------------------------------------------------------------------------
 
+/// The layout of a `Ui`, e.g. horizontal left-aligned.
 #[derive(Clone, Copy, Debug, PartialEq)]
 // #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))]
 pub struct Layout {
@@ -146,7 +147,7 @@ impl Layout {
     /// Reserve this much space and move the cursor.
     /// Returns where to put the widget.
     ///
-    /// # How sizes are negotiated
+    /// ## How sizes are negotiated
     /// Each widget should have a *minimum desired size* and a *desired size*.
     /// When asking for space, ask AT LEAST for you minimum, and don't ask for more than you need.
     /// If you want to fill the space, ask about `available().size()` and use that.

egui/src/lib.rs

@@ -50,7 +50,7 @@ pub use {
     math::*,
     memory::Memory,
     movement_tracker::MovementTracker,
-    paint::{color, Color, TextStyle, Texture},
+    paint::{color, Color, PaintJobs, TextStyle, Texture},
     style::Style,
     types::*,
     ui::Ui,

egui/src/math.rs

@@ -1,5 +1,8 @@
 use std::ops::{Add, AddAssign, Div, Mul, MulAssign, Neg, RangeInclusive, Sub, SubAssign};
 
+/// A size or direction in 2D space.
+///
+/// Normally given in points, e.g. logical pixels.
 #[derive(Clone, Copy, Default)]
 #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))]
 pub struct Vec2 {
@@ -220,7 +223,10 @@ impl std::fmt::Debug for Vec2 {
 
 // ----------------------------------------------------------------------------
 
-/// Sometimes called a Point. I prefer the shorter Pos2 so it is equal length to Vec2
+// Sometimes called a Point. I prefer the shorter Pos2 so it is equal length to Vec2
+/// A position on screen.
+///
+/// Normally given in points, e.g. logical pixels.
 #[derive(Clone, Copy, Default)]
 #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))]
 pub struct Pos2 {
@@ -353,6 +359,9 @@ impl std::fmt::Debug for Pos2 {
 
 // ----------------------------------------------------------------------------
 
+/// A rectangular region of space.
+///
+/// Normally given in points, e.g. logical pixels.
 #[derive(Clone, Copy, Default, Eq, PartialEq)]
 #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))]
 pub struct Rect {
@@ -594,6 +603,11 @@ pub fn ease_in_ease_out(t: f32) -> f32 {
     3.0 * t * t - 2.0 * t * t * t
 }
 
+/// The circumference of a circle divided by its radius.
+///
+/// Represents one turn in radian angles. Equal to `2 * pi`.
+///
+/// See https://tauday.com/
 pub const TAU: f32 = 2.0 * std::f32::consts::PI;
 
 pub fn round_to_precision(value: f32, precision: usize) -> f32 {

egui/src/memory.rs

@@ -6,6 +6,12 @@ use crate::{
     Id, Layer, Pos2, Rect,
 };
 
+/// The data that Egui persists between frames.
+///
+/// This includes window positions and sizes,
+/// how far the user has scrolled in a `ScrollArea` etc.
+///
+/// If you want this to persist when closing your app you should serialize `Memory` and store it.
 #[derive(Clone, Debug, Default)]
 #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "with_serde", serde(default))]
@@ -30,7 +36,7 @@ pub struct Memory {
     pub(crate) areas: Areas,
 }
 
-/// Say there is a butotn in a scroll area.
+/// Say there is a button in a scroll area.
 /// If the user clicks the button, the button should click.
 /// If the user drags the button we should scroll the scroll area.
 /// So what we do is that when the mouse is pressed we register both the button

egui/src/paint/color.rs

@@ -1,5 +1,5 @@
-/// 0-255 `sRGBA`. TODO: rename `sRGBA` for clarity.
-/// Uses premultiplied alpha.
+// TODO: rename `Color` to `sRGBA` for clarity.
+/// 0-255 `sRGBA`. Uses premultiplied alpha.
 #[derive(Clone, Copy, Debug, Default, Eq, Ord, PartialEq, PartialOrd)]
 #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))]
 pub struct Color {

egui/src/paint/fonts.rs

@@ -11,7 +11,7 @@ use super::{
     texture_atlas::{Texture, TextureAtlas},
 };
 
-/// TODO: rename
+// TODO: rename
 #[derive(Copy, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
 // #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))]
 pub enum TextStyle {

egui/src/paint/texture_atlas.rs

@@ -1,7 +1,8 @@
+/// An 8-bit texture containing font data.
 #[derive(Clone, Default)]
 pub struct Texture {
     /// e.g. a hash of the data. Use this to detect changes!
-    pub id: u64, // TODO
+    pub id: u64,
     pub width: usize,
     pub height: usize,
     pub pixels: Vec<u8>,
@@ -25,7 +26,9 @@ impl std::ops::IndexMut<(usize, usize)> for Texture {
     }
 }
 
-/// A texture pixels, used for fonts.
+/// Contains font data in an atlas, where each character occupied a small rectangle.
+///
+/// More characters can be added, possibly expanding the texture.
 #[derive(Clone, Default)]
 pub struct TextureAtlas {
     texture: Texture,

egui/src/style.rs

@@ -3,6 +3,7 @@
 use crate::{color::*, math::*, paint::LineStyle, types::*};
 
 // TODO: split into Spacing and Style?
+/// Specifies the look and feel of a `Ui`.
 #[derive(Clone, Debug)]
 #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))]
 pub struct Style {

egui/src/types.rs

@@ -4,9 +4,12 @@ use crate::{math::Rect, Context, Ui};
 
 // ----------------------------------------------------------------------------
 
+/// What Egui emits each frame.
+/// The backend should use this.
 #[derive(Clone, Default)]
 // #[cfg_attr(feature = "with_serde", derive(serde::Serialize))]
 pub struct Output {
+    /// Set the cursor to this icon.
     pub cursor_icon: CursorIcon,
 
     /// If set, open this url.
@@ -43,6 +46,9 @@ impl Default for CursorIcon {
 
 // ----------------------------------------------------------------------------
 
+/// The result of an interaction.
+///
+/// For instance, this lets you know whether or not a widget has been clicked this frame.
 #[derive(Clone, Copy, Debug)]
 // #[cfg_attr(feature = "with_serde", derive(serde::Serialize))]
 pub struct InteractInfo {
@@ -90,7 +96,10 @@ impl InteractInfo {
 
 // ----------------------------------------------------------------------------
 
-// TODO: rename GuiResponse
+/// The result of adding a widget to an `Ui`.
+///
+/// This lets you know whether or not a widget has been clicked this frame.
+/// It also lets you easily show a tooltip on hover.
 pub struct GuiResponse {
     /// The senses (click or drag) that the widget is interested in (if any).
     pub sense: Sense,