More newlines for improved readability (#1880)

* Add blank lines above all `fn`, `impl`, `struct`, etc
* Even newlines between docstringed struct and enum fields
* Improve some documentation

epaint/src/bezier.rs

@@ -852,6 +852,7 @@ mod tests {
 
         assert_eq!(result.len(), 240);
     }
+
     #[test]
     fn test_cubic_bounding_box() {
         let curve = CubicBezierShape {
@@ -909,6 +910,7 @@ mod tests {
         assert!((bbox.max.x - 199.27).abs() < 0.01);
         assert!((bbox.max.y - 170.0).abs() < 0.01);
     }
+
     #[test]
     fn test_cubic_different_tolerance_flattening() {
         let curve = CubicBezierShape {

epaint/src/color.rs

@@ -587,10 +587,13 @@ pub fn gamma_from_linear(linear: f32) -> f32 {
 pub struct Hsva {
     /// hue 0-1
     pub h: f32,
+
     /// saturation 0-1
     pub s: f32,
+
     /// value 0-1
     pub v: f32,
+
     /// alpha 0-1. A negative value signifies an additive color (and alpha is ignored).
     pub a: f32,
 }
@@ -727,6 +730,7 @@ impl From<Hsva> for Rgba {
         Rgba(hsva.to_rgba_premultiplied())
     }
 }
+
 impl From<Rgba> for Hsva {
     fn from(rgba: Rgba) -> Hsva {
         Self::from_rgba_premultiplied(rgba.0[0], rgba.0[1], rgba.0[2], rgba.0[3])
@@ -738,6 +742,7 @@ impl From<Hsva> for Color32 {
         Color32::from(Rgba::from(hsva))
     }
 }
+
 impl From<Color32> for Hsva {
     fn from(srgba: Color32) -> Hsva {
         Hsva::from(Rgba::from(srgba))
@@ -811,10 +816,13 @@ fn test_hsv_roundtrip() {
 pub struct HsvaGamma {
     /// hue 0-1
     pub h: f32,
+
     /// saturation 0-1
     pub s: f32,
+
     /// value 0-1, in gamma-space (~perceptually even)
     pub v: f32,
+
     /// alpha 0-1. A negative value signifies an additive color (and alpha is ignored).
     pub a: f32,
 }

epaint/src/image.rs

@@ -12,6 +12,7 @@ use crate::{textures::TextureFilter, Color32};
 pub enum ImageData {
     /// RGBA image.
     Color(ColorImage),
+
     /// Used for the font texture.
     Font(FontImage),
 }
@@ -47,6 +48,7 @@ impl ImageData {
 pub struct ColorImage {
     /// width, height.
     pub size: [usize; 2],
+
     /// The pixels, row by row, from top to bottom.
     pub pixels: Vec<Color32>,
 }

epaint/src/lib.rs

@@ -105,6 +105,7 @@ pub struct ClippedPrimitive {
     /// Clip / scissor rectangle.
     /// Only show the part of the [`Mesh`] that falls within this.
     pub clip_rect: emath::Rect,
+
     /// What to paint - either a [`Mesh`] or a [`PaintCallback`].
     pub primitive: Primitive,
 }

epaint/src/shape.rs

@@ -18,22 +18,36 @@ pub use crate::{CubicBezierShape, QuadraticBezierShape};
 pub enum Shape {
     /// Paint nothing. This can be useful as a placeholder.
     Noop,
+
     /// Recursively nest more shapes - sometimes a convenience to be able to do.
     /// For performance reasons it is better to avoid it.
     Vec(Vec<Shape>),
+
+    /// Circle with optional outline and fill.
     Circle(CircleShape),
+
     /// A line between two points.
-    LineSegment {
-        points: [Pos2; 2],
-        stroke: Stroke,
-    },
+    LineSegment { points: [Pos2; 2], stroke: Stroke },
+
     /// A series of lines between points.
     /// The path can have a stroke and/or fill (if closed).
     Path(PathShape),
+
+    /// Rectangle with optional outline and fill.
     Rect(RectShape),
+
+    /// Text.
     Text(TextShape),
+
+    /// A general triangle mesh.
+    ///
+    /// Can be used to display images.
     Mesh(Mesh),
+
+    /// A quadratic [Bézier Curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve).
     QuadraticBezier(QuadraticBezierShape),
+
+    /// A cubic [Bézier Curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve).
     CubicBezier(CubicBezierShape),
 
     /// Backend-specific painting.
@@ -369,11 +383,15 @@ impl From<CircleShape> for Shape {
 pub struct PathShape {
     /// Filled paths should prefer clockwise order.
     pub points: Vec<Pos2>,
+
     /// If true, connect the first and last of the points together.
     /// This is required if `fill != TRANSPARENT`.
     pub closed: bool,
+
     /// Fill is only supported for convex polygons.
     pub fill: Color32,
+
+    /// Color and thickness of the line.
     pub stroke: Stroke,
 }
 
@@ -444,9 +462,14 @@ impl From<PathShape> for Shape {
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
 pub struct RectShape {
     pub rect: Rect,
+
     /// How rounded the corners are. Use `Rounding::none()` for no rounding.
     pub rounding: Rounding,
+
+    /// How to fill the rectangle.
     pub fill: Color32,
+
+    /// The thickness and color of the outline.
     pub stroke: Stroke,
 }
 
@@ -499,10 +522,13 @@ impl From<RectShape> for Shape {
 pub struct Rounding {
     /// Radius of the rounding of the North-West (left top) corner.
     pub nw: f32,
+
     /// Radius of the rounding of the North-East (right top) corner.
     pub ne: f32,
+
     /// Radius of the rounding of the South-West (left bottom) corner.
     pub sw: f32,
+
     /// Radius of the rounding of the South-East (right bottom) corner.
     pub se: f32,
 }

epaint/src/stats.rs

@@ -33,6 +33,7 @@ impl<T> From<&[T]> for AllocInfo {
 
 impl std::ops::Add for AllocInfo {
     type Output = AllocInfo;
+
     fn add(self, rhs: AllocInfo) -> AllocInfo {
         use ElementSize::{Heterogenous, Homogeneous, Unknown};
         let element_size = match (self.element_size, rhs.element_size) {
@@ -113,9 +114,11 @@ impl AllocInfo {
         assert!(self.element_size != ElementSize::Heterogenous);
         self.num_elements
     }
+
     pub fn num_allocs(&self) -> usize {
         self.num_allocs
     }
+
     pub fn num_bytes(&self) -> usize {
         self.num_bytes
     }

epaint/src/text/cursor.rs

@@ -33,6 +33,7 @@ impl PartialEq for CCursor {
 
 impl std::ops::Add<usize> for CCursor {
     type Output = CCursor;
+
     fn add(self, rhs: usize) -> Self::Output {
         CCursor {
             index: self.index.saturating_add(rhs),
@@ -43,6 +44,7 @@ impl std::ops::Add<usize> for CCursor {
 
 impl std::ops::Sub<usize> for CCursor {
     type Output = CCursor;
+
     fn sub(self, rhs: usize) -> Self::Output {
         CCursor {
             index: self.index.saturating_sub(rhs),

epaint/src/text/text_layout.rs

@@ -42,7 +42,9 @@ impl PointScale {
 struct Paragraph {
     /// Start of the next glyph to be added.
     pub cursor_x: f32,
+
     pub glyphs: Vec<Glyph>,
+
     /// In case of an empty paragraph ("\n"), use this as height.
     pub empty_paragraph_height: f32,
 }
@@ -715,16 +717,21 @@ struct RowBreakCandidates {
     /// Breaking at ` ` or other whitespace
     /// is always the primary candidate.
     space: Option<usize>,
+
     /// Logograms (single character representing a whole word) are good candidates for line break.
     logogram: Option<usize>,
+
     /// Kana (Japanese hiragana and katakana) may be line broken unless before a gyōtō kinsoku character.
     kana: Option<usize>,
+
     /// Breaking at a dash is a super-
     /// good idea.
     dash: Option<usize>,
+
     /// This is nicer for things like URLs, e.g. www.
     /// example.com.
     punctuation: Option<usize>,
+
     /// Breaking after just random character is some
     /// times necessary.
     any: Option<usize>,

epaint/src/text/text_layout_types.rs

@@ -395,14 +395,19 @@ impl Default for RowVisuals {
 #[derive(Copy, Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
 pub struct Glyph {
+    /// The character this glyph represents.
     pub chr: char,
+
     /// Relative to the galley position.
     /// Logical position: pos.y is the same for all chars of the same [`TextFormat`].
     pub pos: Pos2,
+
     /// Advance width and font row height.
     pub size: Vec2,
+
     /// Position of the glyph in the font texture, in texels.
     pub uv_rect: UvRect,
+
     /// Index into [`LayoutJob::sections`]. Decides color etc.
     pub section_index: u32,
 }

epaint/src/texture_atlas.rs

@@ -6,10 +6,13 @@ use crate::{textures::TextureFilter, FontImage, ImageDelta};
 struct Rectu {
     /// inclusive
     min_x: usize,
+
     /// inclusive
     min_y: usize,
+
     /// exclusive
     max_x: usize,
+
     /// exclusive
     max_y: usize,
 }
@@ -55,11 +58,13 @@ pub struct PreparedDisc {
 #[derive(Clone)]
 pub struct TextureAtlas {
     image: FontImage,
+
     /// What part of the image that is dirty
     dirty: Rectu,
 
     /// Used for when allocating new rectangles.
     cursor: (usize, usize),
+
     row_height: usize,
 
     /// Set when someone requested more space than was available.

epaint/src/util/ordered_float.rs

@@ -89,7 +89,9 @@ impl FloatOrd for f64 {
 /// Internal abstraction over floating point types
 #[doc(hidden)]
 pub trait Float: PartialOrd + PartialEq + private::FloatImpl {}
+
 impl Float for f32 {}
+
 impl Float for f64 {}
 
 // Keep this trait in private module, to avoid exposing its methods as extensions in user code
@@ -98,6 +100,7 @@ mod private {
 
     pub trait FloatImpl {
         fn is_nan(&self) -> bool;
+
         fn hash<H: Hasher>(&self, state: &mut H);
     }