Improve documentation for the most common widgets

ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # Arcitecture
 This document describes how the crates that make up egui are all connected.
 
-Also see `CONTRIBUTING.md` for what to do before opening a PR.
+Also see [`CONTRIBUTING.md`](https://github.com/emilk/egui/blob/master/CONTRIBUTING.md) for what to do before opening a PR.
 
 
 ## Crate overview

egui/src/lib.rs

@@ -62,6 +62,38 @@
 //! });
 //! ```
 //!
+//! ### Quick start
+//!
+//! ``` rust
+//! # let ui = &mut egui::Ui::__test();
+//! # let mut my_string = String::new();
+//! # let mut my_boolean = true;
+//! # let mut my_f32 = 42.0;
+//! ui.label("This is a label");
+//! ui.hyperlink("https://github.com/emilk/egui");
+//! ui.text_edit_singleline(&mut my_string);
+//! if ui.button("Click me").clicked() { }
+//! ui.add(egui::Slider::f32(&mut my_f32, 0.0..=100.0));
+//! ui.add(egui::DragValue::f32(&mut my_f32));
+//!
+//! ui.checkbox(&mut my_boolean, "Checkbox");
+//!
+//! #[derive(PartialEq)]
+//! enum Enum { First, Second, Third }
+//! let mut my_enum = Enum::First;
+//! ui.horizontal(|ui| {
+//!     ui.radio_value(&mut my_enum, Enum::First, "First");
+//!     ui.radio_value(&mut my_enum, Enum::Second, "Second");
+//!     ui.radio_value(&mut my_enum, Enum::Third, "Third");
+//! });
+//!
+//! ui.separator();
+//!
+//! ui.collapsing("Click to see what is hidden!", |ui| {
+//!     ui.label("Not much, as it turns out");
+//! });
+//! ```
+//!
 //! ## Conventions
 //!
 //! Conventions unless otherwise specified:
@@ -142,9 +174,7 @@
 //! ```
 //! # let ui = &mut egui::Ui::__test();
 //! # let mut some_bool = true;
-//! // Some examples, tips and tricks, etc.
+//! // Miscellaneous tips and tricks
-//!
-//! ui.checkbox(&mut some_bool, "Click to toggle");
 //!
 //! ui.horizontal_wrapped(|ui|{
 //!     ui.spacing_mut().item_spacing.x = 0.0; // remove spacing between widgets
@@ -153,8 +183,6 @@
 //!     ui.radio_value(&mut some_bool, true, "On");
 //! });
 //!
-//! if ui.button("Click me!").clicked() { }
-//!
 //! // Change test color on subsequent widgets:
 //! ui.visuals_mut().override_text_color = Some(egui::Color32::RED);
 //!

egui/src/ui.rs

@@ -877,7 +877,20 @@ impl Ui {
     /// Show a radio button. It is selected if `*current_value == selected_value`.
     /// If clicked, `selected_value` is assigned to `*current_value`.
     ///
-    /// Example: `ui.radio_value(&mut my_enum, Enum::Alternative, "Alternative")`.
+    /// ```
+    /// # let ui = &mut egui::Ui::__test();
+    ///
+    /// #[derive(PartialEq)]
+    /// enum Enum { First, Second, Third }
+    /// let mut my_enum = Enum::First;
+    ///
+    /// ui.radio_value(&mut my_enum, Enum::First, "First");
+    ///
+    /// // is equivalent to:
+    ///
+    /// if ui.add(egui::RadioButton::new(my_enum == Enum::First, "First")).clicked() {
+    ///     my_enum = Enum::First
+    /// }
     pub fn radio_value<Value: PartialEq>(
         &mut self,
         current_value: &mut Value,

egui/src/widgets/button.rs

@@ -1,6 +1,16 @@
 use crate::*;
 
 /// Clickable button with text.
+///
+/// See also [`Ui::button`].
+///
+/// ```
+/// # let ui = &mut egui::Ui::__test();
+/// if ui.add(egui::Button::new("Click mew")).clicked() {
+///     do_stuff();
+/// }
+/// # fn do_stuff() {}
+/// ```
 #[must_use = "You should put this widget in an ui with `ui.add(widget);`"]
 pub struct Button {
     text: String,
@@ -158,6 +168,16 @@ impl Widget for Button {
 
 // TODO: allow checkbox without a text label
 /// Boolean on/off control with text label.
+///
+/// Usually you'd use [`Ui::checkbox`] instead.
+///
+/// ```
+/// # let ui = &mut egui::Ui::__test();
+/// # let mut my_bool = true;
+/// // These are equivalent:
+/// ui.checkbox(&mut my_bool, "Checked");
+/// ui.add(egui::Checkbox::new(&mut my_bool, "Checked"));
+/// ```
 #[must_use = "You should put this widget in an ui with `ui.add(widget);`"]
 #[derive(Debug)]
 pub struct Checkbox<'a> {
@@ -250,6 +270,23 @@ impl<'a> Widget for Checkbox<'a> {
 // ----------------------------------------------------------------------------
 
 /// One out of several alternatives, either selected or not.
+///
+/// Usually you'd use [`Ui::radio_value`] or [`Ui::radio`] instead.
+///
+/// ```
+/// # let ui = &mut egui::Ui::__test();
+/// #[derive(PartialEq)]
+/// enum Enum { First, Second, Third }
+/// let mut my_enum = Enum::First;
+///
+/// ui.radio_value(&mut my_enum, Enum::First, "First");
+///
+/// // is equivalent to:
+///
+/// if ui.add(egui::RadioButton::new(my_enum == Enum::First, "First")).clicked() {
+///     my_enum = Enum::First
+/// }
+/// ```
 #[must_use = "You should put this widget in an ui with `ui.add(widget);`"]
 #[derive(Debug)]
 pub struct RadioButton {

egui/src/widgets/drag_value.rs

@@ -40,6 +40,12 @@ fn set(get_set_value: &mut GetSetValue<'_>, value: f64) {
 }
 
 /// A numeric value that you can change by dragging the number. More compact than a [`Slider`].
+///
+/// ```
+/// # let ui = &mut egui::Ui::__test();
+/// # let mut my_f32: f32 = 0.0;
+/// ui.add(egui::DragValue::f32(&mut my_f32).speed(0.1));
+/// ```
 #[must_use = "You should put this widget in an ui with `ui.add(widget);`"]
 pub struct DragValue<'a> {
     get_set_value: GetSetValue<'a>,

egui/src/widgets/hyperlink.rs

@@ -1,6 +1,14 @@
 use crate::*;
 
 /// A clickable hyperlink, e.g. to `"https://github.com/emilk/egui"`.
+///
+/// See also [`Ui::hyperlink`] and [`Ui::hyperlink_to`].
+///
+/// ```
+/// # let ui = &mut egui::Ui::__test();
+/// ui.hyperlink("https://github.com/emilk/egui");
+/// ui.add(egui::Hyperlink::new("https://github.com/emilk/egui").text("My favorite repo").small());
+/// ```
 #[must_use = "You should put this widget in an ui with `ui.add(widget);`"]
 pub struct Hyperlink {
     url: String,

egui/src/widgets/label.rs

@@ -2,6 +2,13 @@ use crate::*;
 use epaint::Galley;
 
 /// Static text.
+///
+/// ```
+/// # let ui = &mut egui::Ui::__test();
+/// ui.label("Equivalent");
+/// ui.add(egui::Label::new("Equivalent"));
+/// ui.add(egui::Label::new("With Options").text_color(egui::Color32::RED));
+/// ```
 #[must_use = "You should put this widget in an ui with `ui.add(widget);`"]
 pub struct Label {
     // TODO: not pub
@@ -119,7 +126,9 @@ impl Label {
         self.text_color = Some(text_color.into());
         self
     }
+}
 
+impl Label {
     pub fn layout(&self, ui: &Ui) -> Galley {
         let max_width = ui.available_width();
         self.layout_width(ui, max_width)

egui/src/widgets/selected_label.rs

@@ -3,6 +3,23 @@ use crate::*;
 /// One out of several alternatives, either selected or not.
 /// Will mark selected items with a different background color.
 /// An alternative to [`RadioButton`] and [`Checkbox`].
+///
+/// Usually you'd use [`Ui::selectable_value`] or [`Ui::selectable_label`] instead.
+///
+/// ```
+/// # let ui = &mut egui::Ui::__test();
+/// #[derive(PartialEq)]
+/// enum Enum { First, Second, Third }
+/// let mut my_enum = Enum::First;
+///
+/// ui.selectable_value(&mut my_enum, Enum::First, "First");
+///
+/// // is equivalent to:
+///
+/// if ui.add(egui::SelectableLabel::new(my_enum == Enum::First, "First")).clicked() {
+///     my_enum = Enum::First
+/// }
+/// ```
 #[must_use = "You should put this widget in an ui with `ui.add(widget);`"]
 #[derive(Debug)]
 pub struct SelectableLabel {

egui/src/widgets/separator.rs

@@ -1,6 +1,15 @@
 use crate::*;
 
 /// A visual separator. A horizontal or vertical line (depending on [`Layout`]).
+///
+/// Usually you'd use the shorter version [`Ui::separator`].
+///
+/// ```
+/// # let ui = &mut egui::Ui::__test();
+/// // These are equivalent:
+/// ui.separator();
+/// ui.add(egui::Separator::new());
+/// ```
 #[must_use = "You should put this widget in an ui with `ui.add(widget);`"]
 pub struct Separator {
     spacing: f32,

egui/src/widgets/text_edit.rs

@@ -106,6 +106,8 @@ impl CCursorPair {
 
 /// A text region that the user can edit the contents of.
 ///
+/// Se also [`Ui::text_edit_singleline`] and  [`Ui::text_edit_multiline`].
+///
 /// Example:
 ///
 /// ```