Improve various documentation

egui/src/widgets/mod.rs

@@ -28,12 +28,24 @@ 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`].
+/// `[Button]`, `[Label]`, [`Slider`], etc all implement the `Widget` trait.
 ///
-/// `|ui: &mut Ui| -> Response { … }` also implemented `Widget`.
+/// Note that the widgets (`Button`, `TextEdit` etc) are
+/// [builders](https://doc.rust-lang.org/1.0.0/style/ownership/builders.html),
+/// and not objects that hold state.
+///
+/// Tip: you can `impl Widget for &mut YourThing { }`.
+///
+/// `|ui: &mut Ui| -> Response { … }` also implements `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`].
+    ///
+    /// Note that this consumes `self`.
+    /// This is because most widgets ([`Button`], [`TextEdit`] etc) are
+    /// [builders](https://doc.rust-lang.org/1.0.0/style/ownership/builders.html)
+    ///
+    /// Tip: you can `impl Widget for &mut YourObject { }`.
     fn ui(self, ui: &mut Ui) -> Response;
 }
 

epaint/src/shape.rs

@@ -54,6 +54,8 @@ pub enum Shape {
 
 /// ## Constructors
 impl Shape {
+    /// A line between two points.
+    /// More efficient than calling [`Self::line`].
     pub fn line_segment(points: [Pos2; 2], stroke: impl Into<Stroke>) -> Self {
         Self::LineSegment {
             points,
@@ -61,6 +63,9 @@ impl Shape {
         }
     }
 
+    /// A line through many points.
+    ///
+    /// Use [`Self::line_segment`] instead if your line only connect two points.
     pub fn line(points: Vec<Pos2>, stroke: impl Into<Stroke>) -> Self {
         Self::Path {
             points,
@@ -70,6 +75,7 @@ impl Shape {
         }
     }
 
+    /// A line that closes back to the start point again.
     pub fn closed_line(points: Vec<Pos2>, stroke: impl Into<Stroke>) -> Self {
         Self::Path {
             points,

epaint/src/stroke.rs

@@ -1,6 +1,8 @@
 use super::*;
 
 /// Describes the width and color of a line.
+///
+/// The default stroke is the same as [`Stroke::none`].
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 #[cfg_attr(feature = "persistence", derive(serde::Deserialize, serde::Serialize))]
 pub struct Stroke {
@@ -9,6 +11,7 @@ pub struct Stroke {
 }
 
 impl Stroke {
+    /// Same as [`Stroke::default`].
     pub fn none() -> Self {
         Self::new(0.0, Color32::TRANSPARENT)
     }

epaint/src/text/font.rs

@@ -341,20 +341,23 @@ impl Font {
         self.finalize_galley(galley)
     }
 
-    /// Always returns at least one row.
     /// Will line break at `\n`.
+    ///
+    /// Always returns at least one row.
     pub fn layout_no_wrap(&self, text: String) -> Galley {
         self.layout_multiline(text, f32::INFINITY)
     }
 
+    /// Will wrap text at the given width and line break at `\n`.
+    ///
     /// Always returns at least one row.
-    /// Will wrap text at the given width.
     pub fn layout_multiline(&self, text: String, max_width_in_points: f32) -> Galley {
         self.layout_multiline_with_indentation_and_max_width(text, 0.0, max_width_in_points)
     }
 
     /// * `first_row_indentation`: extra space before the very first character (in points).
     /// * `max_width_in_points`: wrapping width.
+    ///
     /// Always returns at least one row.
     pub fn layout_multiline_with_indentation_and_max_width(
         &self,

epaint/src/text/fonts.rs

@@ -315,8 +315,9 @@ impl Fonts {
         self.fonts[&text_style].row_height()
     }
 
-    /// Always returns at least one row.
     /// Will line break at `\n`.
+    ///
+    /// Always returns at least one row.
     pub fn layout_no_wrap(&self, text_style: TextStyle, text: String) -> Arc<Galley> {
         self.layout_multiline(text_style, text, f32::INFINITY)
     }
@@ -338,8 +339,9 @@ impl Fonts {
         )
     }
 
+    /// Will wrap text at the given width and line break at `\n`.
+    ///
     /// Always returns at least one row.
-    /// Will wrap text at the given width.
     pub fn layout_multiline(
         &self,
         text_style: TextStyle,
@@ -356,6 +358,7 @@ impl Fonts {
 
     /// * `first_row_indentation`: extra space before the very first character (in points).
     /// * `max_width_in_points`: wrapping width.
+    ///
     /// Always returns at least one row.
     pub fn layout_multiline_with_indentation_and_max_width(
         &self,