From 53ab2f4ef6a3b9acbc93d139fb82617839b55f72 Mon Sep 17 00:00:00 2001
From: Emil Ernerfeldt <emilernerfeldt@gmail.com>
Date: Sun, 27 Dec 2020 14:16:37 +0100
Subject: [PATCH] Improve documentation

---
 egui/src/containers/collapsing_header.rs |  5 ++--
 egui/src/containers/combo_box.rs         | 31 ++++++++++++++++++++++
 egui/src/containers/frame.rs             |  2 +-
 egui/src/containers/popup.rs             | 26 ++++++++++++++++++-
 egui/src/containers/scroll_area.rs       |  4 +--
 egui/src/paint/command.rs                |  2 ++
 egui/src/paint/fonts.rs                  | 33 ++++++++++++++++++++----
 egui/src/paint/tessellator.rs            | 14 +++++-----
 egui/src/widgets/color_picker.rs         |  2 ++
 egui/src/widgets/mod.rs                  |  4 +--
 10 files changed, 103 insertions(+), 20 deletions(-)

diff --git a/egui/src/containers/collapsing_header.rs b/egui/src/containers/collapsing_header.rs
index e8effc5e..e8ccaf57 100644
--- a/egui/src/containers/collapsing_header.rs
+++ b/egui/src/containers/collapsing_header.rs
@@ -101,7 +101,7 @@ impl State {
 }
 
 /// Paint the arrow icon that indicated if the region is open or not
-pub fn paint_icon(ui: &mut Ui, openness: f32, response: &Response) {
+pub(crate) fn paint_icon(ui: &mut Ui, openness: f32, response: &Response) {
     let stroke = ui.style().interact(response).fg_stroke;
 
     let rect = response.rect;
@@ -118,7 +118,7 @@ pub fn paint_icon(ui: &mut Ui, openness: f32, response: &Response) {
     ui.painter().add(PaintCmd::closed_line(points, stroke));
 }
 
-/// A header which can be collapsed/expanded, revealing a contained `Ui` region.
+/// A header which can be collapsed/expanded, revealing a contained [`Ui`] region.
 pub struct CollapsingHeader {
     label: Label,
     default_open: bool,
@@ -269,6 +269,7 @@ impl CollapsingHeader {
     }
 }
 
+/// The response from showing a [`CollapsingHeader`].
 pub struct CollapsingResponse<R> {
     pub header_response: Response,
     /// None iff collapsed.
diff --git a/egui/src/containers/combo_box.rs b/egui/src/containers/combo_box.rs
index 5ea44b26..49a11843 100644
--- a/egui/src/containers/combo_box.rs
+++ b/egui/src/containers/combo_box.rs
@@ -1,5 +1,20 @@
 use crate::{paint::PaintCmd, style::WidgetVisuals, *};
 
+/// A drop-down selection menu with a descriptive label.
+///
+/// See also [`combo_box`].
+///
+/// ```
+/// # #[derive(Debug, PartialEq)]
+/// # enum Enum { First, Second, Third }
+/// # let mut selected = Enum::First;
+/// # let mut ui = &mut egui::Ui::__test();
+/// egui::combo_box_with_label(ui, "Select one!", format!("{:?}", selected), |ui| {
+///     ui.selectable_value(&mut selected, Enum::First, "First");
+///     ui.selectable_value(&mut selected, Enum::Second, "Second");
+///     ui.selectable_value(&mut selected, Enum::Third, "Third");
+/// });
+/// ```
 pub fn combo_box_with_label(
     ui: &mut Ui,
     label: impl Into<Label>,
@@ -17,6 +32,22 @@ pub fn combo_box_with_label(
     .0
 }
 
+/// A drop-down selection menu.
+///
+/// See also [`combo_box_with_label`].
+///
+/// ```
+/// # #[derive(Debug, PartialEq)]
+/// # enum Enum { First, Second, Third }
+/// # let mut selected = Enum::First;
+/// # let mut ui = &mut egui::Ui::__test();
+/// let id = ui.make_persistent_id("my_combo_box");
+/// egui::combo_box(ui, id, format!("{:?}", selected), |ui| {
+///     ui.selectable_value(&mut selected, Enum::First, "First");
+///     ui.selectable_value(&mut selected, Enum::Second, "Second");
+///     ui.selectable_value(&mut selected, Enum::Third, "Third");
+/// });
+/// ```
 pub fn combo_box(
     ui: &mut Ui,
     button_id: Id,
diff --git a/egui/src/containers/frame.rs b/egui/src/containers/frame.rs
index 2add1142..5fe551a8 100644
--- a/egui/src/containers/frame.rs
+++ b/egui/src/containers/frame.rs
@@ -2,7 +2,7 @@
 
 use crate::{layers::PaintCmdIdx, paint::*, *};
 
-/// Adds a rectangular frame and background to some `Ui`.
+/// Adds a rectangular frame and background to some [`Ui`].
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub struct Frame {
     // On each side
diff --git a/egui/src/containers/popup.rs b/egui/src/containers/popup.rs
index bd40f0b3..8b66a228 100644
--- a/egui/src/containers/popup.rs
+++ b/egui/src/containers/popup.rs
@@ -1,6 +1,19 @@
 use crate::*;
 
 /// Show a tooltip at the current mouse position (if any).
+///
+/// Most of the time it is easier to use [`Response::on_hover_ui`].
+///
+/// See also [`show_tooltip_text`].
+///
+/// ```
+/// # let mut ui = egui::Ui::__test();
+/// if ui.ui_contains_mouse() {
+///     egui::show_tooltip(ui.ctx(), |ui| {
+///         ui.label("Helpful text");
+///     });
+/// }
+/// ```
 pub fn show_tooltip(ctx: &CtxRef, add_contents: impl FnOnce(&mut Ui)) {
     let tooltip_rect = ctx.memory().tooltip_rect;
 
@@ -24,7 +37,18 @@ pub fn show_tooltip(ctx: &CtxRef, add_contents: impl FnOnce(&mut Ui)) {
     ctx.memory().tooltip_rect = Some(tooltip_rect.union(response.rect));
 }
 
-/// Show a tooltip at the current mouse position (if any).
+/// Show some text at the current mouse position (if any).
+///
+/// Most of the time it is easier to use [`Response::on_hover_text`].
+///
+/// See also [`show_tooltip`].
+///
+/// ```
+/// # let mut ui = egui::Ui::__test();
+/// if ui.ui_contains_mouse() {
+///     egui::show_tooltip_text(ui.ctx(), "Helpful text");
+/// }
+/// ```
 pub fn show_tooltip_text(ctx: &CtxRef, text: impl Into<String>) {
     show_tooltip(ctx, |ui| {
         ui.add(crate::widgets::Label::new(text));
diff --git a/egui/src/containers/scroll_area.rs b/egui/src/containers/scroll_area.rs
index 779962b3..d1fd13ac 100644
--- a/egui/src/containers/scroll_area.rs
+++ b/egui/src/containers/scroll_area.rs
@@ -25,7 +25,7 @@ impl Default for State {
 }
 
 // TODO: rename VScroll
-/// Add vertical scrolling to a contained `Ui`.
+/// Add vertical scrolling to a contained [`Ui`].
 #[derive(Clone, Debug)]
 pub struct ScrollArea {
     max_height: f32,
@@ -34,7 +34,7 @@ pub struct ScrollArea {
 }
 
 impl ScrollArea {
-    /// Will make the area be as high as it is allowed to be (i.e. fill the ui it is in)
+    /// Will make the area be as high as it is allowed to be (i.e. fill the [`Ui`] it is in)
     pub fn auto_sized() -> Self {
         Self::from_max_height(f32::INFINITY)
     }
diff --git a/egui/src/paint/command.rs b/egui/src/paint/command.rs
index f6220b73..1ef1dcff 100644
--- a/egui/src/paint/command.rs
+++ b/egui/src/paint/command.rs
@@ -32,6 +32,7 @@ pub enum PaintCmd {
     },
     Rect {
         rect: Rect,
+        /// How rounded the corners are. Use `0.0` for no rounding.
         corner_radius: f32,
         fill: Srgba,
         stroke: Stroke,
@@ -184,6 +185,7 @@ impl PaintCmd {
     }
 }
 
+/// Describes the width and color of a line.
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
 pub struct Stroke {
diff --git a/egui/src/paint/fonts.rs b/egui/src/paint/fonts.rs
index 66e6d948..df5b744b 100644
--- a/egui/src/paint/fonts.rs
+++ b/egui/src/paint/fonts.rs
@@ -12,14 +12,20 @@ use super::{
 };
 
 // TODO: rename
+/// One of a few categories of styles of text, e.g. body, button or heading.
 #[derive(Copy, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
 pub enum TextStyle {
+    /// Used when small text is needed.
     Small,
+    /// Normal labels. Easily readable, doesn't take up too much space.
     Body,
+    /// Buttons. Maybe slightly bigger than `Body`.
     Button,
+    /// Heading. Probably larger than `Body`.
     Heading,
+    /// Same size as `Body`, but used when monospace is important (for aligning number, code snippets, etc).
     Monospace,
 }
 
@@ -37,10 +43,13 @@ impl TextStyle {
     }
 }
 
+/// Which style of font: [`Monospace`][`FontFamily::Monospace`] or [`VariableWidth`][`FontFamily::VariableWidth`].
 #[derive(Copy, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
 // #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
 pub enum FontFamily {
+    /// A font where each character is the same width (`w` is the same width as `i`).
     Monospace,
+    /// A font where some characters are wider than other (e.g. 'w' is wider than 'i').
     VariableWidth,
 }
 
@@ -55,11 +64,25 @@ fn rusttype_font_from_font_data(name: &str, data: &FontData) -> rusttype::Font<'
     .unwrap_or_else(|| panic!("Error parsing {:?} TTF/OTF font file", name))
 }
 
-/// This is how you tell Egui which fonts and font sizes to use.
+/// Describes the font data and the sizes to use.
+///
+/// This is how you can tell Egui which fonts and font sizes to use.
+///
+/// Often you would start with [`FontDefinitions::default()`] and then add/change the contents.
+///
+/// ```
+/// # let mut ctx = egui::CtxRef::default();
+/// let mut fonts = egui::FontDefinitions::default();
+/// // Large button text:
+/// fonts.family_and_size.insert(
+///     egui::TextStyle::Button,
+///     (egui::FontFamily::VariableWidth, 32.0));
+/// ctx.set_fonts(fonts);
+/// ```
 #[derive(Clone, Debug, PartialEq)]
 pub struct FontDefinitions {
     /// The dpi scale factor. Needed to get pixel perfect fonts.
-    pub pixels_per_point: f32,
+    pub pixels_per_point: f32, // TODO: remove from here
 
     /// List of font names and their definitions.
     /// The definition must be the contents of either a `.ttf` or `.otf` font file.
@@ -68,15 +91,15 @@ pub struct FontDefinitions {
     /// but you can override them if you like.
     pub font_data: BTreeMap<String, FontData>,
 
-    /// Which fonts (names) to use for each `FontFamily`.
+    /// Which fonts (names) to use for each [`FontFamily`].
     ///
-    /// The list should be a list of keys into `font_data`.
+    /// The list should be a list of keys into [`Self::font_data`].
     /// When looking for a character glyph Egui will start with
     /// the first font and then move to the second, and so on.
     /// So the first font is the primary, and then comes a list of fallbacks in order of priority.
     pub fonts_for_family: BTreeMap<FontFamily, Vec<String>>,
 
-    /// The `FontFaily` and size you want to use for a specific `TextStyle`.
+    /// The [`FontFamily`] and size you want to use for a specific [`TextStyle`].
     pub family_and_size: BTreeMap<TextStyle, (FontFamily, f32)>,
 }
 
diff --git a/egui/src/paint/tessellator.rs b/egui/src/paint/tessellator.rs
index 58f0d46f..5bd3c05d 100644
--- a/egui/src/paint/tessellator.rs
+++ b/egui/src/paint/tessellator.rs
@@ -1,7 +1,7 @@
 //! Converts graphics primitives into textured triangles.
 //!
-//! This module converts lines, circles, text and more represented by `PaintCmd`
-//! into textured triangles represented by `Triangles`.
+//! This module converts lines, circles, text and more represented by [`PaintCmd`]
+//! into textured triangles represented by [`Triangles`].
 
 #![allow(clippy::identity_op)]
 
@@ -15,11 +15,11 @@ use {
     std::f32::consts::TAU,
 };
 
-/// What texture to use in a `Triangles` mesh.
+/// What texture to use in a [`Triangles`] mesh.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub enum TextureId {
     /// The Egui font texture.
-    /// If you don't want to use a texture, pick this and the `WHITE_UV` for uv-coord.
+    /// If you don't want to use a texture, pick this and the [`WHITE_UV`] for uv-coord.
     Egui,
 
     /// Your own texture, defined in any which way you want.
@@ -665,7 +665,7 @@ fn mul_color(color: Srgba, factor: f32) -> Srgba {
 
 // ----------------------------------------------------------------------------
 
-/// Tesselate a single `PaintCmd` into a `Triangles`.
+/// Tesselate a single [`PaintCmd`] into a [`Triangles`].
 ///
 /// * `command`: the command to tesselate
 /// * `options`: tesselation quality
@@ -845,7 +845,7 @@ fn tesselate_text(
     assert_eq!(chars.next(), None);
 }
 
-/// Turns `PaintCmd`:s into sets of triangles.
+/// Turns [`PaintCmd`]:s into sets of triangles.
 ///
 /// The given commands will be painted back-to-front (painters algorithm).
 /// They will be batched together by clip rectangle.
@@ -855,7 +855,7 @@ fn tesselate_text(
 /// * `fonts`: font source when tessellating text
 ///
 /// ## Returns
-/// A list of clip rectangles with matching `Triangles`.
+/// A list of clip rectangles with matching [`Triangles`].
 pub fn tessellate_paint_commands(
     commands: Vec<(Rect, PaintCmd)>,
     options: TesselationOptions,
diff --git a/egui/src/widgets/color_picker.rs b/egui/src/widgets/color_picker.rs
index 9656648d..6226badd 100644
--- a/egui/src/widgets/color_picker.rs
+++ b/egui/src/widgets/color_picker.rs
@@ -1,3 +1,5 @@
+//! Color picker widgets.
+
 use crate::{
     paint::{color::*, *},
     *,
diff --git a/egui/src/widgets/mod.rs b/egui/src/widgets/mod.rs
index cc63bf39..5aebfb1a 100644
--- a/egui/src/widgets/mod.rs
+++ b/egui/src/widgets/mod.rs
@@ -299,7 +299,7 @@ impl Widget for Hyperlink {
 
 // ----------------------------------------------------------------------------
 
-/// Clickable button with text
+/// Clickable button with text.
 #[must_use = "You should put this widget in an ui with `ui.add(widget);`"]
 pub struct Button {
     text: String,
@@ -438,7 +438,7 @@ impl Widget for Button {
 // ----------------------------------------------------------------------------
 
 // TODO: allow checkbox without a text label
-/// Boolean on/off control with text label
+/// Boolean on/off control with text label.
 #[derive(Debug)]
 pub struct Checkbox<'a> {
     checked: &'a mut bool,