From de204b54361ce2362091faf40f9d87d0455d7591 Mon Sep 17 00:00:00 2001
From: Emil Ernerfeldt <emilernerfeldt@gmail.com>
Date: Sat, 6 Feb 2021 11:48:57 +0100
Subject: [PATCH] Improve documentation of style-related functions and types

---
 egui/src/context.rs | 14 ++++++++++++--
 egui/src/style.rs   | 34 +++++++++++++++++++++-------------
 egui/src/ui.rs      | 32 ++++++++++++++++++++++++++++----
 3 files changed, 61 insertions(+), 19 deletions(-)

diff --git a/egui/src/context.rs b/egui/src/context.rs
index 3884f840..0c92625d 100644
--- a/egui/src/context.rs
+++ b/egui/src/context.rs
@@ -452,17 +452,27 @@ impl Context {
         self.memory().options.font_definitions = font_definitions;
     }
 
-    /// The [`Style`] used by all new windows, panels etc.
+    /// The [`Style`] used by all subsequent windows, panels etc.
     pub fn style(&self) -> Arc<Style> {
         self.memory().options.style.clone()
     }
 
     /// The [`Style`] used by all new windows, panels etc.
+    ///
+    /// Example:
+    /// ```
+    /// # let mut ctx = egui::CtxRef::default();
+    /// let mut style: egui::Style = (*ctx.style()).clone();
+    /// style.spacing.item_spacing = egui::vec2(10.0, 20.0);
+    /// ctx.set_style(style);
+    /// ```
     pub fn set_style(&self, style: impl Into<Arc<Style>>) {
         self.memory().options.style = style.into();
     }
 
-    /// The [`Visuals`] used by all new windows, panels etc.
+    /// The [`Visuals`] used by all subsequent windows, panels etc.
+    ///
+    /// You can also use [`Ui::visuals_mut`] to change the visuals of a single [`Ui`].
     ///
     /// Example:
     /// ```
diff --git a/egui/src/style.rs b/egui/src/style.rs
index 093a2b00..e02c0d53 100644
--- a/egui/src/style.rs
+++ b/egui/src/style.rs
@@ -113,6 +113,9 @@ pub struct Interaction {
 pub struct Visuals {
     /// If true, the visuals are overall dark with light text.
     /// If false, the visuals are overall light with dark text.
+    ///
+    /// NOTE: setting this does very little by itself,
+    /// this is more to provide a convenient summary of the rest of the settings.
     pub dark_mode: bool,
 
     /// Override default text color for all text.
@@ -197,15 +200,18 @@ pub struct Selection {
 #[cfg_attr(feature = "persistence", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "persistence", serde(default))]
 pub struct Widgets {
-    /// For a non-interactive widget
+    /// The style of a widget that you cannot interact with.
+    /// * `noninteractive.bg_stroke` is the outline of windows.
+    /// * `noninteractive.bg_fill` is the background color of windows.
+    /// * `noninteractive.fg_stroke` is the normal text color.
     pub noninteractive: WidgetVisuals,
-    /// For an otherwise interactive widget that has been disabled
+    /// The style of a disabled button.
     pub disabled: WidgetVisuals,
-    /// For an interactive widget that is "resting"
+    /// The style of an interactive widget, such as a button, at rest.
     pub inactive: WidgetVisuals,
-    /// For an interactive widget that is being hovered
+    /// The style of an interactive widget while you hover it.
     pub hovered: WidgetVisuals,
-    /// For an interactive widget that is being interacted with
+    /// The style of an interactive widget as you are clicking or dragging it.
     pub active: WidgetVisuals,
 }
 
@@ -227,7 +233,7 @@ impl Widgets {
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[cfg_attr(feature = "persistence", derive(serde::Deserialize, serde::Serialize))]
 pub struct WidgetVisuals {
-    /// Background color of widget
+    /// Background color of widget.
     pub bg_fill: Color32,
 
     /// For surrounding rectangle of things that need it,
@@ -235,13 +241,13 @@ pub struct WidgetVisuals {
     /// Should maybe be called `frame_stroke`.
     pub bg_stroke: Stroke,
 
-    /// Button frames etc
+    /// Button frames etc.
     pub corner_radius: f32,
 
-    /// Stroke and text color of the interactive part of a component (button text, slider grab, check-mark, ...)
+    /// Stroke and text color of the interactive part of a component (button text, slider grab, check-mark, ...).
     pub fg_stroke: Stroke,
 
-    /// Make the frame this much larger
+    /// Make the frame this much larger.
     pub expansion: f32,
 }
 
@@ -292,6 +298,7 @@ impl Default for Interaction {
 }
 
 impl Visuals {
+    /// Default dark theme.
     pub fn dark() -> Self {
         Self {
             dark_mode: true,
@@ -312,6 +319,7 @@ impl Visuals {
         }
     }
 
+    /// Default light theme.
     pub fn light() -> Self {
         Self {
             dark_mode: false,
@@ -532,7 +540,7 @@ impl Widgets {
         } = self;
 
         ui.collapsing("noninteractive", |ui| {
-            ui.label("The style of something that you cannot interact with.");
+            ui.label("The style of a widget that you cannot interact with.");
             noninteractive.ui(ui)
         });
         ui.collapsing("interactive & disabled", |ui| {
@@ -540,15 +548,15 @@ impl Widgets {
             disabled.ui(ui)
         });
         ui.collapsing("interactive & inactive", |ui| {
-            ui.label("The style of a widget, such as a button, at rest.");
+            ui.label("The style of an interactive widget, such as a button, at rest.");
             inactive.ui(ui)
         });
         ui.collapsing("interactive & hovered", |ui| {
-            ui.label("The style of a widget while you hover it.");
+            ui.label("The style of an interactive widget while you hover it.");
             hovered.ui(ui)
         });
         ui.collapsing("interactive & active", |ui| {
-            ui.label("The style of a widget as you are clicking or dragging it.");
+            ui.label("The style of an interactive widget as you are clicking or dragging it.");
             active.ui(ui)
         });
 
diff --git a/egui/src/ui.rs b/egui/src/ui.rs
index 616a1702..737455d7 100644
--- a/egui/src/ui.rs
+++ b/egui/src/ui.rs
@@ -99,35 +99,59 @@ impl Ui {
 
     /// Mutably borrow internal `Style`.
     /// Changes apply to this `Ui` and its subsequent children.
+    ///
+    /// To set the style of all `Ui`:s, use [`Context::set_style`].
+    ///
+    /// Example:
+    /// ```
+    /// # let ui = &mut egui::Ui::__test();
+    /// ui.style_mut().body_text_style = egui::TextStyle::Heading;
+    /// ```
     pub fn style_mut(&mut self) -> &mut Style {
         std::sync::Arc::make_mut(&mut self.style) // clone-on-write
     }
 
     /// Changes apply to this `Ui` and its subsequent children.
+    ///
+    /// To set the visuals of all `Ui`:s, use [`Context::set_visuals`].
     pub fn set_style(&mut self, style: impl Into<std::sync::Arc<Style>>) {
         self.style = style.into();
     }
 
-    /// Short for `&self.style().spacing`
-    /// Spacing options for this `Ui` and its children.
+    /// The current spacing options for this `Ui`.
+    /// Short for `ui.style().spacing`.
     pub fn spacing(&self) -> &crate::style::Spacing {
         &self.style.spacing
     }
 
     /// Mutably borrow internal `Spacing`.
     /// Changes apply to this `Ui` and its subsequent children.
+    ///
+    /// Example:
+    /// ```
+    /// # let ui = &mut egui::Ui::__test();
+    /// ui.spacing_mut().item_spacing = egui::vec2(10.0, 2.0);
+    /// ```
     pub fn spacing_mut(&mut self) -> &mut crate::style::Spacing {
         &mut self.style_mut().spacing
     }
 
-    /// Short for `&self.style().visuals`
-    /// visuals options for this `Ui` and its children.
+    /// The current visuals settings of this `Ui`.
+    /// Short for `ui.style().visuals`.
     pub fn visuals(&self) -> &crate::Visuals {
         &self.style.visuals
     }
 
     /// Mutably borrow internal `visuals`.
     /// Changes apply to this `Ui` and its subsequent children.
+    ///
+    /// To set the visuals of all `Ui`:s, use [`Context::set_visuals`].
+    ///
+    /// Example:
+    /// ```
+    /// # let ui = &mut egui::Ui::__test();
+    /// ui.visuals_mut().override_text_color = Some(egui::Color32::RED);
+    /// ```
     pub fn visuals_mut(&mut self) -> &mut crate::Visuals {
         &mut self.style_mut().visuals
     }