Documentation improvements

Author: emilk

CONTRIBUTING.md

@@ -62,6 +62,7 @@ While using an immediate mode gui is simple, implementing one is a lot more tric
 * read some code before writing your own
 * follow the `egui` code style
 * add blank lines around all `fn`, `struct`, `enum`, etc.
+* `// Comment like this`, not `//like this`
 * write idiomatic rust
 * avoid `unsafe`
 * avoid code that can cause panics

egui/src/widgets/text_edit/builder.rs

@@ -8,7 +8,7 @@ use super::{CCursorRange, CursorRange, TextEditOutput, TextEditState};
 
 /// A text region that the user can edit the contents of.
 ///
-/// See also [`Ui::text_edit_singleline`] and  [`Ui::text_edit_multiline`].
+/// See also [`Ui::text_edit_singleline`] and [`Ui::text_edit_multiline`].
 ///
 /// Example:
 ///

egui_demo_lib/src/easy_mark/easy_mark_highlighter.rs

@@ -61,22 +61,22 @@ pub fn highlight_easymark(egui_style: &egui::Style, mut text: &str) -> egui::tex
         if text.starts_with('\\') && text.len() >= 2 {
             skip = 2;
         } else if start_of_line && text.starts_with(' ') {
-            // indentation we don't preview indentation, because it is confusing
+            // we don't preview indentation, because it is confusing
             skip = 1;
         } else if start_of_line && text.starts_with("# ") {
             style.heading = true;
             skip = 2;
         } else if start_of_line && text.starts_with("> ") {
             style.quoted = true;
             skip = 2;
-            // indentation we don't preview indentation, because it is confusing
+            // we don't preview indentation, because it is confusing
         } else if start_of_line && text.starts_with("- ") {
             skip = 2;
-            // indentation we don't preview indentation, because it is confusing
+            // we don't preview indentation, because it is confusing
         } else if text.starts_with('*') {
             skip = 1;
             if style.strong {
-                // Include the character that i ending ths style:
+                // Include the character that is ending this style:
                 job.append(&text[..skip], 0.0, format_from_style(egui_style, &style));
                 text = &text[skip..];
                 skip = 0;
@@ -85,7 +85,7 @@ pub fn highlight_easymark(egui_style: &egui::Style, mut text: &str) -> egui::tex
         } else if text.starts_with('$') {
             skip = 1;
             if style.small {
-                // Include the character that i ending ths style:
+                // Include the character that is ending this style:
                 job.append(&text[..skip], 0.0, format_from_style(egui_style, &style));
                 text = &text[skip..];
                 skip = 0;
@@ -94,7 +94,7 @@ pub fn highlight_easymark(egui_style: &egui::Style, mut text: &str) -> egui::tex
         } else if text.starts_with('^') {
             skip = 1;
             if style.raised {
-                // Include the character that i ending ths style:
+                // Include the character that is ending this style:
                 job.append(&text[..skip], 0.0, format_from_style(egui_style, &style));
                 text = &text[skip..];
                 skip = 0;

egui_demo_lib/src/easy_mark/easy_mark_parser.rs

@@ -1,9 +1,6 @@
 //! A parser for `EasyMark`: a very simple markup language.
 //!
 //! WARNING: `EasyMark` is subject to change.
-//!
-//! This module does not depend on anything else in egui
-//! and should perhaps be its own crate.
 //
 //! # `EasyMark` design goals:
 //! 1. easy to parse

emath/src/rect.rs

@@ -5,18 +5,29 @@ use crate::*;
 
 /// A rectangular region of space.
 ///
-/// Normally given in points, e.g. logical pixels.
+/// Usually a `Rect` has a positive (or zero) size,
+/// and then [`Self::min`] `<=` [`Self::max`].
+/// In these cases [`Self::min`] is the left-top corner
+/// and [`Self::max`] is the right-bottom corner.
+///
+/// A rectangle is allowed to have a negative size, which happens when the order
+/// of `min` and `max` are swapped. These are usually a sign of an error.
+///
+/// Normally the unit is points (logical pixels) in screen space coordinates.
 #[repr(C)]
 #[derive(Clone, Copy, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
 #[cfg_attr(feature = "bytemuck", derive(bytemuck::Pod, bytemuck::Zeroable))]
 pub struct Rect {
+    /// One of the corners of the rectangle, usually the left top one.
     pub min: Pos2,
+
+    /// The other corner, opposing [`Self::min`]. Usually the right bottom one.
     pub max: Pos2,
 }
 
 impl Rect {
-    /// Infinite rectangle that contains everything.
+    /// Infinite rectangle that contains every point.
     pub const EVERYTHING: Self = Self {
         min: pos2(-INFINITY, -INFINITY),
         max: pos2(INFINITY, INFINITY),
@@ -25,19 +36,14 @@ impl Rect {
     /// The inverse of [`Self::EVERYTHING`]: stretches from positive infinity to negative infinity.
     /// Contains no points.
     ///
-    /// This is useful as the seed for bounding bounding boxes.
-    ///
-    /// ```
-    /// # use emath::*;
-    /// let inf = f32::INFINITY;
-    /// assert!(Rect::NOTHING.size() == Vec2::splat(-inf));
-    /// assert!(Rect::NOTHING.contains(pos2(0.0, 0.0)) == false);
-    /// ```
+    /// This is useful as the seed for bounding boxes.
     ///
     /// # Example:
     /// ```
     /// # use emath::*;
     /// let mut rect = Rect::NOTHING;
+    /// assert!(rect.size() == Vec2::splat(-f32::INFINITY));
+    /// assert!(rect.contains(pos2(0.0, 0.0)) == false);
     /// rect.extend_with(pos2(2.0, 1.0));
     /// rect.extend_with(pos2(0.0, 3.0));
     /// assert_eq!(rect, Rect::from_min_max(pos2(0.0, 1.0), pos2(2.0, 3.0)))
@@ -50,14 +56,15 @@ impl Rect {
     /// An invalid `Rect` filled with [`f32::NAN`];
     pub const NAN: Self = Self {
         min: pos2(f32::NAN, f32::NAN),
-        max: pos2(-f32::NAN, -f32::NAN),
+        max: pos2(f32::NAN, f32::NAN),
     };
 
     #[inline(always)]
     pub const fn from_min_max(min: Pos2, max: Pos2) -> Self {
         Rect { min, max }
     }
 
+    /// left-top corner plus a size (stretching right-down).
     #[inline(always)]
     pub fn from_min_size(min: Pos2, size: Vec2) -> Self {
         Rect {
@@ -82,6 +89,7 @@ impl Rect {
         }
     }
 
+    /// Returns the bounding rectangle of the two points.
     #[inline]
     pub fn from_two_pos(a: Pos2, b: Pos2) -> Self {
         Rect {
@@ -90,7 +98,7 @@ impl Rect {
         }
     }
 
-    /// Bounding-box around the points
+    /// Bounding-box around the points.
     pub fn from_points(points: &[Pos2]) -> Self {
         let mut rect = Rect::NOTHING;
         for &p in points {