Finish documenting GPUI

crates/gpui/src/text_system/line.rs

@@ -6,19 +6,29 @@ use derive_more::{Deref, DerefMut};
 use smallvec::SmallVec;
 use std::sync::Arc;
 
+/// Set the text decoration for a run of text.
 #[derive(Debug, Clone)]
 pub struct DecorationRun {
+    /// The length of the run in utf-8 bytes.
     pub len: u32,
+
+    /// The color for this run
     pub color: Hsla,
+
+    /// The background color for this run
     pub background_color: Option<Hsla>,
+
+    /// The underline style for this run
     pub underline: Option<UnderlineStyle>,
 }
 
+/// A line of text that has been shaped and decorated.
 #[derive(Clone, Default, Debug, Deref, DerefMut)]
 pub struct ShapedLine {
     #[deref]
     #[deref_mut]
     pub(crate) layout: Arc<LineLayout>,
+    /// The text that was shaped for this line.
     pub text: SharedString,
     pub(crate) decoration_runs: SmallVec<[DecorationRun; 32]>,
 }
@@ -30,6 +40,7 @@ impl ShapedLine {
         self.layout.len
     }
 
+    /// Paint the line of text to the window.
     pub fn paint(
         &self,
         origin: Point<Pixels>,
@@ -49,21 +60,25 @@ impl ShapedLine {
     }
 }
 
+/// A line of text that has been shaped, decorated, and wrapped by the text layout system.
 #[derive(Clone, Default, Debug, Deref, DerefMut)]
 pub struct WrappedLine {
     #[deref]
     #[deref_mut]
     pub(crate) layout: Arc<WrappedLineLayout>,
+    /// The text that was shaped for this line.
     pub text: SharedString,
     pub(crate) decoration_runs: SmallVec<[DecorationRun; 32]>,
 }
 
 impl WrappedLine {
+    /// The length of the underlying, unwrapped layout, in utf-8 bytes.
     #[allow(clippy::len_without_is_empty)]
     pub fn len(&self) -> usize {
         self.layout.len()
     }
 
+    /// Paint this line of text to the window.
     pub fn paint(
         &self,
         origin: Point<Pixels>,

crates/gpui/src/text_system/line_layout.rs

@@ -8,31 +8,50 @@ use std::{
     sync::Arc,
 };
 
+/// A laid out and styled line of text
 #[derive(Default, Debug)]
 pub struct LineLayout {
+    /// The font size for this line
     pub font_size: Pixels,
+    /// The width of the line
     pub width: Pixels,
+    /// The ascent of the line
     pub ascent: Pixels,
+    /// The descent of the line
     pub descent: Pixels,
+    /// The shaped runs that make up this line
     pub runs: Vec<ShapedRun>,
+    /// The length of the line in utf-8 bytes
     pub len: usize,
 }
 
+/// A run of text that has been shaped .
 #[derive(Debug)]
 pub struct ShapedRun {
+    /// The font id for this run
     pub font_id: FontId,
+    /// The glyphs that make up this run
     pub glyphs: SmallVec<[ShapedGlyph; 8]>,
 }
 
+/// A single glyph, ready to paint.
 #[derive(Clone, Debug)]
 pub struct ShapedGlyph {
+    /// The ID for this glyph, as determined by the text system.
     pub id: GlyphId,
+
+    /// The position of this glyph in it's containing line.
     pub position: Point<Pixels>,
+
+    /// The index of this glyph in the original text.
     pub index: usize,
+
+    /// Whether this glyph is an emoji
     pub is_emoji: bool,
 }
 
 impl LineLayout {
+    /// The index for the character at the given x coordinate
     pub fn index_for_x(&self, x: Pixels) -> Option<usize> {
         if x >= self.width {
             None
@@ -71,6 +90,7 @@ impl LineLayout {
         self.len
     }
 
+    /// The x position of the character at the given index
     pub fn x_for_index(&self, index: usize) -> Pixels {
         for run in &self.runs {
             for glyph in &run.glyphs {
@@ -148,31 +168,44 @@ impl LineLayout {
     }
 }
 
+/// A line of text that has been wrapped to fit a given width
 #[derive(Default, Debug)]
 pub struct WrappedLineLayout {
+    /// The line layout, pre-wrapping.
     pub unwrapped_layout: Arc<LineLayout>,
+
+    /// The boundaries at which the line was wrapped
     pub wrap_boundaries: SmallVec<[WrapBoundary; 1]>,
+
+    /// The width of the line, if it was wrapped
     pub wrap_width: Option<Pixels>,
 }
 
+/// A boundary at which a line was wrapped
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
 pub struct WrapBoundary {
+    /// The index in the run just before the line was wrapped
     pub run_ix: usize,
+    /// The index of the glyph just before the line was wrapped
     pub glyph_ix: usize,
 }
 
 impl WrappedLineLayout {
+    /// The length of the underlying text, in utf8 bytes.
     #[allow(clippy::len_without_is_empty)]
     pub fn len(&self) -> usize {
         self.unwrapped_layout.len
     }
 
+    /// The width of this line, in pixels, whether or not it was wrapped.
     pub fn width(&self) -> Pixels {
         self.wrap_width
             .unwrap_or(Pixels::MAX)
             .min(self.unwrapped_layout.width)
     }
 
+    /// The size of the whole wrapped text, for the given line_height.
+    /// can span multiple lines if there are multiple wrap boundaries.
     pub fn size(&self, line_height: Pixels) -> Size<Pixels> {
         Size {
             width: self.width(),
@@ -180,26 +213,32 @@ impl WrappedLineLayout {
         }
     }
 
+    /// The ascent of a line in this layout
     pub fn ascent(&self) -> Pixels {
         self.unwrapped_layout.ascent
     }
 
+    /// The descent of a line in this layout
     pub fn descent(&self) -> Pixels {
         self.unwrapped_layout.descent
     }
 
+    /// The wrap boundaries in this layout
     pub fn wrap_boundaries(&self) -> &[WrapBoundary] {
         &self.wrap_boundaries
     }
 
+    /// The font size of this layout
     pub fn font_size(&self) -> Pixels {
         self.unwrapped_layout.font_size
     }
 
+    /// The runs in this layout, sans wrapping
     pub fn runs(&self) -> &[ShapedRun] {
         &self.unwrapped_layout.runs
     }
 
+    /// The index corresponding to a given position in this layout for the given line height.
     pub fn index_for_position(
         &self,
         position: Point<Pixels>,
@@ -377,6 +416,7 @@ impl LineLayoutCache {
     }
 }
 
+/// A run of text with a single font.
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
 pub struct FontRun {
     pub(crate) len: usize,

crates/gpui/src/text_system/line_wrapper.rs

@@ -2,6 +2,7 @@ use crate::{px, FontId, FontRun, Pixels, PlatformTextSystem};
 use collections::HashMap;
 use std::{iter, sync::Arc};
 
+/// The GPUI line wrapper, used to wrap lines of text to a given width.
 pub struct LineWrapper {
     platform_text_system: Arc<dyn PlatformTextSystem>,
     pub(crate) font_id: FontId,
@@ -11,6 +12,7 @@ pub struct LineWrapper {
 }
 
 impl LineWrapper {
+    /// The maximum indent that can be applied to a line.
     pub const MAX_INDENT: u32 = 256;
 
     pub(crate) fn new(
@@ -27,6 +29,7 @@ impl LineWrapper {
         }
     }
 
+    /// Wrap a line of text to the given width with this wrapper's font and font size.
     pub fn wrap_line<'a>(
         &'a mut self,
         line: &'a str,
@@ -122,9 +125,12 @@ impl LineWrapper {
     }
 }
 
+/// A boundary between two lines of text.
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub struct Boundary {
+    /// The index of the last character in a line
     pub ix: usize,
+    /// The indent of the next line.
     pub next_indent: u32,
 }