Improve documentation

egui/src/lib.rs

@@ -1,8 +1,6 @@
-//! egui:  an easy-to-use GUI in pure Rust
+//! `egui`:  an easy-to-use GUI in pure Rust!
 //!
-//! Try the live web demo: <https://emilk.github.io/egui/index.html>.
-//!
-//! Read more about egui at <https://github.com/emilk/egui>.
+//! Try the live web demo: <https://emilk.github.io/egui/index.html>. Read more about egui at <https://github.com/emilk/egui>.
 //!
 //! To quickly get started with egui, you can take a look at [`egui_template`](https://github.com/emilk/egui_template)
 //! which uses [`eframe`](https://docs.rs/eframe).
@@ -45,6 +43,10 @@
 //!
 //! To see what is possible to build we egui you can check out the online demo at <https://emilk.github.io/egui/#demo>.
 //!
+//! If you like the "learning by doing" approach, clone <https://github.com/emilk/egui_template> and get started using egui right away.
+//!
+//! ### Getting a [`Ui`]
+//!
 //! Use one of [`SidePanel`], [`TopPanel`], [`CentralPanel`], [`Window`] or [`Area`] to
 //! get access to an [`Ui`] where you can put widgets. For example:
 //!
@@ -60,6 +62,80 @@
 //! });
 //! ```
 //!
+//! ## Conventions
+//!
+//! Conventions unless otherwise specified:
+//!
+//! * angles are in radians
+//! * `Vec2::X` is right and `Vec2::Y` is down.
+//! * `Pos2::ZERO` is left top.
+//!
+//!
+//! ## Understanding immediate mode
+//!
+//! `egui` is an immediate mode GUI library. It is useful to fully grok what "immediate mode" implies.
+//!
+//! Here is an example to illustrate it:
+//!
+//! ```
+//! # let ui = &mut egui::Ui::__test();
+//! if ui.button("click me").clicked() { take_action() }
+//! # fn take_action() {}
+//! ```
+//!
+//! This code is being executed each frame at maybe 60 frames per second.
+//! Each frame egui does these things:
+//!
+//! * lays out the letters `click me` in order to figure out the size of the button
+//! * decides where on screen to place the button
+//! * check if the mouse is hovering or clicking that location
+//! * chose button colors based on if it is being hovered or clicked
+//! * add a [`Shape::Rect`] and [`Shape::Text`] to the list of shapes to be painted later this frame
+//! * return a [`Response`] with the `clicked` member so the user can check for interactions
+//!
+//! There is no button being created and stored somewhere.
+//! The only output of this call is some colored shapes, and a [`Response`].
+//!
+//! Read more about the pros and cons of immediate mode at <https://github.com/emilk/egui#why-immediate-mode>.
+//!
+//! ## How widgets works
+//!
+//! ```
+//! # let ui = &mut egui::Ui::__test();
+//! if ui.button("click me").clicked() { take_action() }
+//! # fn take_action() {}
+//! ```
+//!
+//! is short for
+//!
+//! ```
+//! # let ui = &mut egui::Ui::__test();
+//! let button = egui::Button::new("click me");
+//! if ui.add(button).clicked() { take_action() }
+//! # fn take_action() {}
+//! ```
+//!
+//! which is short for
+//!
+//! ```
+//! # use egui::Widget;
+//! # let ui = &mut egui::Ui::__test();
+//! let button = egui::Button::new("click me");
+//! let response = button.ui(ui);
+//! if response.clicked() { take_action() }
+//! # fn take_action() {}
+//! ```
+//!
+//! [`Button`] uses the builder pattern to create the data required to show it. The [`Button`] is then discarded.
+//!
+//! [`Button`] implements `trait` [`Widget`], which looks like this:
+//! ```
+//! # use egui::*;
+//! pub trait Widget {
+//!     /// Allocate space, interact, paint, and return a [`Response`].
+//!     fn ui(self, ui: &mut Ui) -> Response;
+//! }
+//! ```
 //!
 //! # Code snippets
 //!

egui/src/widgets/mod.rs

@@ -29,6 +29,10 @@ pub use {button::*, drag_value::DragValue, image::Image, slider::*, text_edit::*
 // ----------------------------------------------------------------------------
 
 /// Anything implementing Widget can be added to a [`Ui`] with [`Ui::add`].
+///
+/// Examples include `[Button]`, `[Label]` and [`Slider`].
+///
+/// `|ui: &mut Ui| -> Response { … }` also implemented `Widget`.
 #[must_use = "You should put this widget in an ui with `ui.add(widget);`"]
 pub trait Widget {
     /// Allocate space, interact, paint, and return a [`Response`].

egui/src/widgets/selected_label.rs

@@ -1,7 +1,7 @@
 use crate::*;
 
 /// One out of several alternatives, either selected or not.
-/// Will mark selected items with a different background color
+/// Will mark selected items with a different background color.
 /// An alternative to [`RadioButton`] and [`Checkbox`].
 #[must_use = "You should put this widget in an ui with `ui.add(widget);`"]
 #[derive(Debug)]