Improve documentation

CHANGELOG.md

@@ -19,8 +19,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ### Changed 🔧
 
 * New simpler and sleeker look!
-* Center window titles.
-* Tweak size and alignment of some emojis to match other text.
 * Rename `PaintCmd` to `Shape`.
 * Replace tuple `(Rect, Shape)` with tuple-struct `ClippedShape`.
 * Rename feature `"serde"` to `"persistence"`.
@@ -31,6 +29,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Fixed a bug that would sometimes trigger a "Mismatching panels" panic in debug builds.
 * `Image` and `ImageButton` will no longer stretch to fill a justified layout.
 
+
 ## 0.7.0 - 2021-01-04
 
 ### Added ⭐

docs/index.html

@@ -75,3 +75,5 @@
 </body>
 
 </html>
+
+<!-- Powered by Egui: https://github.com/emilk/egui/ -->

eframe/src/lib.rs

@@ -1,11 +1,15 @@
 //! eframe - the Egui Framework crate
 //!
-//! You write your application code for [`epi`] (implementing [`epi::App`]) and then
-//! use eframe to either compile and run it natively, or compile it as a web app.
+//! If you are planning to write an app for web or native,
+//! and are happy with just using Egui for all visuals,
+//! Then `eframe` is for you!
 //!
 //! To get started, look at <https://github.com/emilk/egui_template>.
 //!
-//! eframe is implemented using [`egui_web`](https://docs.rs/egui_web) and [`egui_glium`](https://docs.rs/egui_glium).
+//! You write your application code for [`epi`] (implementing [`epi::App`]) and then
+//! call from [`crate::run_native`] your `main.rs`, and/or call `eframe::start_web` from your `lib.rs`.
+//!
+//! `eframe` is implemented using [`egui_web`](https://docs.rs/egui_web) and [`egui_glium`](https://docs.rs/egui_glium).
 
 #![forbid(unsafe_code)]
 #![cfg_attr(not(debug_assertions), deny(warnings))] // Forbid warnings in release builds
@@ -23,7 +27,7 @@ pub use egui_web::wasm_bindgen;
 /// and start running the given app.
 ///
 /// Usage:
-/// ``` ignore
+/// ``` no_run
 /// #[cfg(target_arch = "wasm32")]
 /// use wasm_bindgen::prelude::*;
 ///

egui/src/grid.rs

@@ -193,7 +193,7 @@ impl GridLayout {
 
 // ----------------------------------------------------------------------------
 
-/// A simple `Grid` layout.
+/// A simple grid layout.
 ///
 /// The contents of each cell be aligned to the left and center.
 /// If you want to add multiple widgets to a cell you need to group them with
@@ -209,6 +209,11 @@ impl GridLayout {
 ///     ui.label("Second row, first column");
 ///     ui.label("Second row, second column");
 ///     ui.label("Second row, third column");
+///     ui.end_row();
+///
+///     ui.horizontal(|ui| { ui.label("Same"); ui.label("cell"); });
+///     ui.label("Third row, second column");
+///     ui.end_row();
 /// });
 /// ```
 pub struct Grid {
@@ -220,6 +225,7 @@ pub struct Grid {
 }
 
 impl Grid {
+    /// Create a new [`Grid`] with a locally unique identifier.
     pub fn new(id_source: impl std::hash::Hash) -> Self {
         Self {
             id_source: Id::new(id_source),

egui/src/layers.rs

@@ -1,3 +1,6 @@
+//! Handles paint layers, i.e. how things
+//! are sometimes painted behind or in front of other things.
+
 use crate::{math::Rect, Id, *};
 use epaint::ahash::AHashMap;
 use epaint::{ClippedShape, Shape};

egui/src/lib.rs

@@ -156,7 +156,7 @@ pub fn warn_if_debug_build(ui: &mut crate::Ui) {
 
 // ----------------------------------------------------------------------------
 
-/// Create a [`Hyperlink`](crate::Hyperlink) to this file (and line) on Github
+/// Create a [`Hyperlink`](crate::Hyperlink) to the current [`file!()`] (and line) on Github
 ///
 /// Example: `ui.add(github_link_file_line!("https://github.com/YOUR/PROJECT/blob/master/", "(source code)"));`
 #[macro_export]
@@ -167,7 +167,7 @@ macro_rules! github_link_file_line {
     }};
 }
 
-/// Create a [`Hyperlink`](crate::Hyperlink) to this file on github.
+/// Create a [`Hyperlink`](crate::Hyperlink) to the current [`file!()`] on github.
 ///
 /// Example: `ui.add(github_link_file!("https://github.com/YOUR/PROJECT/blob/master/", "(source code)"));`
 #[macro_export]

emath/src/align.rs

@@ -2,7 +2,7 @@
 
 use crate::*;
 
-/// left/center/right or top/center/bottom alignment for e.g. anchors and `Layout`s.
+/// left/center/right or top/center/bottom alignment for e.g. anchors and layouts.
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]

emath/src/lib.rs

@@ -1,4 +1,6 @@
-//! Vectors, positions, rectangles etc.
+//! Opinionated 2D math library for building GUIs.
+//!
+//! Includes vectors, positions, rectangles etc.
 //!
 //! Conventions (unless otherwise specified):
 //!
@@ -127,7 +129,7 @@ where
     lerp(to, t)
 }
 
-/// Like `remap`, but also clamps the value so that the returned value is always in the `to` range.
+/// Like [`remap`], but also clamps the value so that the returned value is always in the `to` range.
 pub fn remap_clamp<T>(x: T, from: RangeInclusive<T>, to: RangeInclusive<T>) -> T
 where
     T: Real,

epaint/src/color.rs

@@ -1,3 +1,5 @@
+//! Color conversions and types.
+
 use emath::clamp;
 
 /// This format is used for space-efficient color representation (32 bits).

epaint/src/lib.rs

@@ -47,7 +47,7 @@
 pub mod color;
 pub mod mutex;
 mod shadow;
-pub mod shape;
+mod shape;
 pub mod stats;
 mod stroke;
 pub mod tessellator;
@@ -108,7 +108,7 @@ pub(crate) struct PaintRect {
 #[derive(Clone, Debug)]
 pub struct ClippedShape(
     /// Clip / scissor rectangle.
-    /// Only show the part of the [`shape`] that falls within this.
+    /// Only show the part of the [`Shape`] that falls within this.
     pub emath::Rect,
     /// The shape
     pub Shape,

epaint/src/shadow.rs

@@ -1,5 +1,6 @@
 use super::*;
 
+/// A rectangular shadow with a soft penumbra.
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 #[cfg_attr(feature = "persistence", derive(serde::Deserialize, serde::Serialize))]
 pub struct Shadow {

epaint/src/stats.rs

@@ -1,5 +1,8 @@
+//! Collect statistics about what is being painted.
+
 use crate::*;
 
+/// Size of the elements in a vector/array.
 #[derive(Clone, Copy, PartialEq)]
 enum ElementSize {
     Unknown,
@@ -13,6 +16,7 @@ impl Default for ElementSize {
     }
 }
 
+/// Aggregate information about a bunch of allocations.
 #[derive(Clone, Copy, Default, PartialEq)]
 pub struct AllocInfo {
     element_size: ElementSize,
@@ -131,6 +135,7 @@ impl AllocInfo {
     }
 }
 
+/// Collected allocation statistics for shapes and meshes.
 #[derive(Clone, Copy, Default)]
 pub struct PaintStats {
     pub shapes: AllocInfo,

epaint/src/text/fonts.rs

@@ -66,18 +66,14 @@ fn rusttype_font_from_font_data(name: &str, data: &FontData) -> rusttype::Font<'
 
 /// 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.
 ///
-/// ``` ignore
-/// # let mut ctx = egui::CtxRef::default();
-/// let mut fonts = egui::FontDefinitions::default();
+/// ```
+/// let mut fonts = epaint::text::FontDefinitions::default();
 /// // Large button text:
 /// fonts.family_and_size.insert(
-///     egui::TextStyle::Button,
-///     (egui::FontFamily::Proportional, 32.0));
-/// ctx.set_fonts(fonts);
+///     epaint::text::TextStyle::Button,
+///     (epaint::text::FontFamily::Proportional, 32.0));
 /// ```
 #[derive(Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "persistence", derive(serde::Deserialize, serde::Serialize))]
@@ -86,7 +82,7 @@ pub struct FontDefinitions {
     /// List of font names and their definitions.
     /// The definition must be the contents of either a `.ttf` or `.otf` font file.
     ///
-    /// Egui has built-in-default for these,
+    /// `epaint` has built-in-default for these,
     /// but you can override them if you like.
     #[cfg_attr(feature = "persistence", serde(skip))]
     pub font_data: BTreeMap<String, FontData>,
@@ -94,7 +90,7 @@ pub struct FontDefinitions {
     /// Which fonts (names) to use for each [`FontFamily`].
     ///
     /// The list should be a list of keys into [`Self::font_data`].
-    /// When looking for a character glyph Egui will start with
+    /// When looking for a character glyph `epaint` 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>>,
@@ -175,7 +171,7 @@ impl Default for FontDefinitions {
     }
 }
 
-/// The collection of fonts used by Egui.
+/// The collection of fonts used by `epaint`.
 ///
 /// Note: `Fonts::default()` is invalid (missing `pixels_per_point`).
 #[derive(Default)]

epaint/src/text/mod.rs

@@ -1,3 +1,5 @@
+//! Everything related to text, fonts, text layout, cursors etc.
+
 pub mod cursor;
 mod font;
 mod fonts;

epi/src/lib.rs

@@ -160,7 +160,7 @@ impl<'a> Frame<'a> {
     }
 }
 
-/// Information about the web environment
+/// Information about the web environment (if applicable).
 #[derive(Clone, Debug)]
 pub struct WebInfo {
     /// e.g. "#fragment" part of "www.example.com/index.html#fragment".