[doc] improve docstrings in Egui

egui/src/containers.rs

@@ -1,3 +1,7 @@
+//! Containers are pieces of the UI which wraps other pieces of UI.
+//!
+//! For instance, a `Frame` adds a frame and background to some contained UI.
+
 pub(crate) mod area;
 pub(crate) mod collapsing_header;
 pub(crate) mod frame;

egui/src/containers/area.rs

@@ -6,6 +6,7 @@ use std::{fmt::Debug, hash::Hash, sync::Arc};
 
 use crate::*;
 
+/// State that is persisted between frames
 #[derive(Clone, Copy, Debug)]
 #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))]
 pub(crate) struct State {
@@ -31,6 +32,9 @@ impl State {
     }
 }
 
+/// An area on the screen that can be move by dragging.
+///
+/// This forms the base of the `Window` container.
 #[derive(Clone, Copy, Debug)]
 pub struct Area {
     id: Id,

egui/src/containers/collapsing_header.rs

@@ -146,6 +146,7 @@ impl State {
     }
 }
 
+/// A header which can be collapsed/expanded, revealing a contained `Ui` region.
 pub struct CollapsingHeader {
     label: Label,
     default_open: bool,

egui/src/containers/frame.rs

@@ -2,6 +2,7 @@
 
 use crate::{layers::PaintCmdIdx, paint::*, *};
 
+/// Adds a rectangular frame and background to some `Ui`.
 #[derive(Clone, Debug, Default)]
 pub struct Frame {
     // On each side

egui/src/containers/popup.rs

@@ -2,6 +2,7 @@ use std::sync::Arc;
 
 use crate::*;
 
+/// Show a tooltip at the current mouse position (if any).
 pub fn show_tooltip(ctx: &Arc<Context>, add_contents: impl FnOnce(&mut Ui)) {
     if let Some(mouse_pos) = ctx.input().mouse.pos {
         //  TODO: default size
@@ -11,7 +12,7 @@ pub fn show_tooltip(ctx: &Arc<Context>, add_contents: impl FnOnce(&mut Ui)) {
     }
 }
 
-/// Show a pop-over window
+/// Show a pop-over window.
 pub fn show_popup(
     ctx: &Arc<Context>,
     id: Id,

egui/src/containers/resize.rs

@@ -16,6 +16,7 @@ pub(crate) struct State {
     pub(crate) requested_size: Option<Vec2>,
 }
 
+/// A region that can be resized by dragging the bottom right corner.
 #[derive(Clone, Copy, Debug)]
 pub struct Resize {
     id: Option<Id>,

egui/src/containers/scroll_area.rs

@@ -26,6 +26,7 @@ impl Default for State {
 }
 
 // TODO: rename VScroll
+/// Add vertical scrolling to a contained `Ui`.
 #[derive(Clone, Debug)]
 pub struct ScrollArea {
     max_height: f32,

egui/src/containers/window.rs

@@ -4,7 +4,7 @@ use crate::{paint::*, widgets::*, *};
 
 use super::*;
 
-/// A wrapper around other containers for things you often want in a window
+/// A floating window which can be moved, closed, collapsed, resized and scrolled.
 pub struct Window<'open> {
     pub title_label: Label,
     open: Option<&'open mut bool>,

egui/src/input.rs

@@ -151,6 +151,7 @@ impl Default for MouseInput {
     }
 }
 
+/// An input event. Only covers events used by Egui.
 #[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
 pub enum Event {
     Copy,
@@ -164,6 +165,7 @@ pub enum Event {
     },
 }
 
+/// Keyboard key name. Only covers keys used by Egui.
 #[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
 pub enum Key {
     Alt,

egui/src/layers.rs

@@ -34,6 +34,7 @@ impl Layer {
     }
 }
 
+/// A unique identifier of a specific `PaintCmd` in a `PaintList`.
 #[derive(Clone, Copy, PartialEq)]
 pub struct PaintCmdIdx(usize);
 
@@ -54,6 +55,12 @@ impl PaintList {
     }
 
     /// Modify an existing command.
+    ///
+    /// Sometimes you want to paint a frame behind some contents, but don't know how large the frame needs to be
+    /// until the contents have been added, and therefor also painted to the `PaintList`.
+    ///
+    /// The solution is to allocate a `PaintCmd` using `let idx = paint_list.add(cr, PaintCmd::Noop);`
+    /// and then later setting it using `paint_list.set(idx, cr, frame);`.
     pub fn set(&mut self, idx: PaintCmdIdx, clip_rect: Rect, cmd: PaintCmd) {
         assert!(idx.0 < self.0.len());
         self.0[idx.0] = (clip_rect, cmd);

egui/src/layout.rs

@@ -2,6 +2,7 @@ use crate::{math::*, style::Style};
 
 // ----------------------------------------------------------------------------
 
+/// `Layout` direction (horizontal or vertical).
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "with_serde", serde(rename_all = "snake_case"))]
@@ -16,6 +17,7 @@ impl Default for Direction {
     }
 }
 
+/// left/center/right or top/center/bottom alignment for e.g. anchors and `Layout`s.
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "with_serde", serde(rename_all = "snake_case"))]

egui/src/math.rs

@@ -1,3 +1,5 @@
+//! Vectors, positions, rectangles etc.
+
 use std::ops::{Add, AddAssign, Div, Mul, MulAssign, Neg, RangeInclusive, Sub, SubAssign};
 
 /// A size or direction in 2D space.
@@ -122,6 +124,18 @@ impl Vec2 {
         vec2(self.x.max(other.x), self.y.max(other.y))
     }
 
+    /// Returns the minimum of `self.x` and `self.y`.
+    #[must_use]
+    pub fn min_elem(self) -> f32 {
+        self.x.min(self.y)
+    }
+
+    /// Returns the maximum of `self.x` and `self.y`.
+    #[must_use]
+    pub fn max_elem(self) -> f32 {
+        self.x.max(self.y)
+    }
+
     #[must_use]
     pub fn clamp(self, range: RangeInclusive<Self>) -> Self {
         Self {
@@ -575,6 +589,7 @@ impl std::fmt::Debug for Rect {
 
 // ----------------------------------------------------------------------------
 
+/// Linear interpolation.
 pub fn lerp<T>(range: RangeInclusive<T>, t: f32) -> T
 where
     f32: Mul<T, Output = T>,
@@ -583,11 +598,15 @@ where
     (1.0 - t) * *range.start() + t * *range.end()
 }
 
+/// Linearly remap a value from one range to another,
+/// so that when `x == from.start()` returns `to.start()`
+/// and when `x == from.end()` returns `to.end()`.
 pub fn remap(x: f32, from: RangeInclusive<f32>, to: RangeInclusive<f32>) -> f32 {
     let t = (x - from.start()) / (from.end() - from.start());
     lerp(to, t)
 }
 
+/// Like `remap`, but also clamps the value so that the returned value is always in the `to` range.
 pub fn remap_clamp(x: f32, from: RangeInclusive<f32>, to: RangeInclusive<f32>) -> f32 {
     if x <= *from.start() {
         *to.start()
@@ -604,6 +623,9 @@ pub fn remap_clamp(x: f32, from: RangeInclusive<f32>, to: RangeInclusive<f32>) -
     }
 }
 
+/// Returns `range.start()` if `x <= range.start()`,
+/// returns `range.end()` if `x >= range.end()`
+/// and returns `x` elsewhen.
 pub fn clamp<T>(x: T, range: RangeInclusive<T>) -> T
 where
     T: Copy + PartialOrd,
@@ -629,9 +651,10 @@ pub fn ease_in_ease_out(t: f32) -> f32 {
 /// See <https://tauday.com/>
 pub const TAU: f32 = 2.0 * std::f32::consts::PI;
 
-pub fn round_to_precision(value: f32, precision: usize) -> f32 {
+/// Round a value to the given number of decimal places.
+pub fn round_to_precision(value: f32, decimal_places: usize) -> f32 {
     // This is a stupid way of doing this, but stupid works.
-    format!("{:.*}", precision, value)
+    format!("{:.*}", decimal_places, value)
         .parse()
         .unwrap_or_else(|_| value)
 }

egui/src/menu.rs

@@ -17,9 +17,10 @@
 
 use crate::{widgets::*, *};
 
+/// What is saved between frames.
 #[derive(Clone, Copy, Debug)]
 #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))]
-pub struct BarState {
+pub(crate) struct BarState {
     #[cfg_attr(feature = "with_serde", serde(skip))]
     open_menu: Option<Id>,
     #[cfg_attr(feature = "with_serde", serde(skip))]

egui/src/paint.rs

@@ -1,3 +1,7 @@
+//! Graphics module.
+//!
+//! Handles fonts, textures, color, geometry and tesselation.
+
 pub mod color;
 pub mod command;
 pub mod font;

egui/src/paint/tessellator.rs

@@ -9,25 +9,29 @@ use {
     crate::math::*,
 };
 
+/// The UV coordinate of a white region of the texture mesh.
 const WHITE_UV: (u16, u16) = (1, 1);
 
 #[derive(Clone, Copy, Debug, Default)]
 pub struct Vertex {
-    /// Pixel coordinates
+    /// Logical pixel coordinates (points)
     pub pos: Pos2,
-    /// Texel indices into the texture
+    /// Texel coordinates in the texture
     pub uv: (u16, u16),
-    /// sRGBA, premultiplied alpha
+    /// sRGBA with premultiplied alpha
     pub color: Color,
 }
 
+/// Textured triangles
 #[derive(Clone, Debug, Default)]
 pub struct Triangles {
-    /// Draw as triangles (i.e. the length is a multiple of three)
+    /// Draw as triangles (i.e. the length is always multiple of three).
     pub indices: Vec<u32>,
+    /// The vertex data indexed by `indices`.
     pub vertices: Vec<Vertex>,
 }
 
+/// A clip triangle and some textured triangles.
 pub type PaintJob = (Rect, Triangles);
 
 /// Grouped by clip rectangles, in pixel coordinates
@@ -82,7 +86,7 @@ impl Triangles {
         self.vertices.push(bottom_right);
     }
 
-    /// This is for platsform that only support 16-bit index buffers.
+    /// This is for platforms that only support 16-bit index buffers.
     /// Splits this mesh into many small if needed.
     /// All the returned meshes will have indices that fit into a `u16`.
     pub fn split_to_u16(self) -> Vec<Triangles> {
@@ -150,6 +154,7 @@ pub struct PathPoint {
     normal: Vec2,
 }
 
+/// A 2D path that can be tesselated into triangles.
 #[derive(Clone, Debug, Default)]
 pub struct Path(Vec<PathPoint>);
 
@@ -313,9 +318,11 @@ use self::PathType::{Closed, Open};
 
 #[derive(Clone, Copy)]
 pub struct PaintOptions {
+    /// Anti-aliasing makes shapes appear smoother, but requires more triangles and is therefore slower.
     pub anti_alias: bool,
     /// Size of a pixel in points, e.g. 0.5
     pub aa_size: f32,
+    /// Output the clip rectangles to be painted?
     pub debug_paint_clip_rects: bool,
 }
 
@@ -442,6 +449,7 @@ pub fn paint_path_outline(
                 i0 = i1;
             }
         } else {
+            // thick line
             // TODO: line caps for really thick lines?
 
             /*

egui/src/ui.rs

@@ -374,15 +374,15 @@ impl Ui {
     /// for `Justified` aligned layouts, like in menus.
     ///
     /// You may get LESS space than you asked for if the current layout won't fit what you asked for.
-    pub fn allocate_space(&mut self, child_size: Vec2) -> Rect {
+    pub fn allocate_space(&mut self, desired_size: Vec2) -> Rect {
-        let child_size = self.painter().round_vec_to_pixels(child_size);
+        let desired_size = self.painter().round_vec_to_pixels(desired_size);
         self.cursor = self.painter().round_pos_to_pixels(self.cursor);
 
         // For debug rendering
-        let too_wide = child_size.x > self.available().width();
+        let too_wide = desired_size.x > self.available().width();
-        let too_high = child_size.x > self.available().height();
+        let too_high = desired_size.x > self.available().height();
 
-        let rect = self.reserve_space_impl(child_size);
+        let rect = self.reserve_space_impl(desired_size);
 
         if self.style().debug_widget_rects {
             self.painter.add(PaintCmd::Rect {
@@ -429,8 +429,11 @@ impl Ui {
     }
 
     /// Ask to allocate a certain amount of space and return a Painter for that region.
-    pub fn allocate_canvas(&mut self, size: Vec2) -> Painter {
+    ///
-        let rect = self.allocate_space(size);
+    /// You may get back a `Painter` with a smaller or larger size than what you desired,
+    /// depending on the avilable space and the current layout.
+    pub fn allocate_canvas(&mut self, desired_size: Vec2) -> Painter {
+        let rect = self.allocate_space(desired_size);
         self.painter_at(rect)
     }
 }

egui/src/widgets.rs

@@ -1,7 +1,7 @@
+//! Widgets are pieces of GUI such as labels, buttons, sliders etc.
+//!
 //! Example widget uses:
-//!
+//! * `ui.add(Label::new("Text").text_color(color::red));`//!
-//! * `ui.add(Label::new("Text").text_color(color::red));`
-//!
 //! * `if ui.add(Button::new("Click me")).clicked { ... }`
 
 #![allow(clippy::new_without_default)]
@@ -24,6 +24,7 @@ pub trait Widget {
 
 // ----------------------------------------------------------------------------
 
+/// Static text.
 pub struct Label {
     // TODO: not pub
     pub(crate) text: String,
@@ -146,6 +147,7 @@ impl Into<Label> for String {
 
 // ----------------------------------------------------------------------------
 
+/// A clickable hyperlink, e.g. to `"https://github.com/emilk/emigui/"`.
 pub struct Hyperlink {
     url: String,
     text: String,
@@ -210,6 +212,7 @@ impl Widget for Hyperlink {
 
 // ----------------------------------------------------------------------------
 
+/// Clickable button with text
 pub struct Button {
     text: String,
     text_color: Option<Color>,
@@ -298,6 +301,8 @@ impl Widget for Button {
 
 // ----------------------------------------------------------------------------
 
+// TODO: allow checkbox without a text label
+/// Boolean on/off control with text label
 #[derive(Debug)]
 pub struct Checkbox<'a> {
     checked: &'a mut bool,
@@ -375,6 +380,7 @@ impl<'a> Widget for Checkbox<'a> {
 
 // ----------------------------------------------------------------------------
 
+/// One out of several alternatives, either checked or not.
 #[derive(Debug)]
 pub struct RadioButton {
     checked: bool,
@@ -448,6 +454,7 @@ impl Widget for RadioButton {
 
 // ----------------------------------------------------------------------------
 
+/// A visual separator. A horizontal or vertical line (depending on `Layout`).
 pub struct Separator {
     line_width: Option<f32>,
     spacing: f32,
@@ -537,6 +544,7 @@ impl Widget for Separator {
 
 // ----------------------------------------------------------------------------
 
+/// A floating point value that you can change by dragging the number. More compact than a slider.
 pub struct DragValue<'a> {
     value: &'a mut f32,
     speed: f32,

egui/src/widgets/slider.rs

@@ -6,6 +6,7 @@ use crate::{paint::*, widgets::Label, *};
 /// for the borrow checker.
 type SliderGetSet<'a> = Box<dyn 'a + FnMut(Option<f32>) -> f32>;
 
+/// Control a number by a horizontal slider.
 pub struct Slider<'a> {
     get_set_value: SliderGetSet<'a>,
     range: RangeInclusive<f32>,

egui/src/widgets/text_edit.rs

@@ -8,6 +8,7 @@ pub(crate) struct State {
     pub cursor: Option<usize>,
 }
 
+/// A text region that the user can edit the contents of.
 #[derive(Debug)]
 pub struct TextEdit<'t> {
     text: &'t mut String,

egui_glium/README.md

@@ -0,0 +1,3 @@
+# egui_glium
+
+This crates provides bindings between [Egui](crates.io/crates/egui) and [glium](https://crates.io/crates/glium) which allows you to write GUI code using Egui and compile it and run it natively, cross platform.

egui_web/README.md

@@ -0,0 +1,5 @@
+# egui_web
+
+This crates allows you to compile GUI code written with [Egui](crates.io/crates/egui) to [WASM](https://en.wikipedia.org/wiki/WebAssembly) to run on a web page.
+
+Check out [docs/index.html](https://github.com/emilk/emigui/blob/master/docs/index.html), [demo_web](https://github.com/emilk/emigui/tree/master/demo_web) and [build_web.sh](https://github.com/emilk/emigui/blob/master/build_web.sh) for examples of how to set it up.