Write documentation for the new text APIs

2 files changed, 75 insertions, 6 deletions

diff --git a/core/src/text/editor.rs b/core/src/text/editor.rs
index e9d66ce9..ebb0eee2 100644
--- a/core/src/text/editor.rs
+++ b/core/src/text/editor.rs
@@ -1,25 +1,36 @@
+//! Edit text.
 use crate::text::highlighter::{self, Highlighter};
 use crate::text::LineHeight;
 use crate::{Pixels, Point, Rectangle, Size};
 
 use std::sync::Arc;
 
+/// A component that can be used by widgets to edit multi-line text.
 pub trait Editor: Sized + Default {
+    /// The [`Font`] of the [`Editor`].
     type Font: Copy + PartialEq + Default;
 
     /// Creates a new [`Editor`] laid out with the given text.
     fn with_text(text: &str) -> Self;
 
+    /// Returns the current [`Cursor`] of the [`Editor`].
     fn cursor(&self) -> Cursor;
 
+    /// Returns the current cursor position of the [`Editor`].
+    ///
+    /// Line and column, respectively.
     fn cursor_position(&self) -> (usize, usize);
 
+    /// Returns the current selected text of the [`Editor`].
     fn selection(&self) -> Option<String>;
 
+    /// Returns the text of the given line in the [`Editor`], if it exists.
     fn line(&self, index: usize) -> Option<&str>;
 
+    /// Returns the amount of lines in the [`Editor`].
     fn line_count(&self) -> usize;
 
+    /// Performs an [`Action`] on the [`Editor`].
     fn perform(&mut self, action: Action);
 
     /// Returns the current boundaries of the [`Editor`].
@@ -35,6 +46,7 @@ pub trait Editor: Sized + Default {
         new_highlighter: &mut impl Highlighter,
     );
 
+    /// Runs a text [`Highlighter`] in the [`Editor`].
     fn highlight<H: Highlighter>(
         &mut self,
         font: Self::Font,
@@ -43,50 +55,83 @@ pub trait Editor: Sized + Default {
     );
 }
 
+/// An interaction with an [`Editor`].
 #[derive(Debug, Clone, PartialEq)]
 pub enum Action {
+    /// Apply a [`Motion`].
     Move(Motion),
+    /// Select text with a given [`Motion`].
     Select(Motion),
+    /// Select the word at the current cursor.
     SelectWord,
+    /// Select the line at the current cursor.
     SelectLine,
+    /// Perform an [`Edit`].
     Edit(Edit),
+    /// Click the [`Editor`] at the given [`Point`].
     Click(Point),
+    /// Drag the mouse on the [`Editor`] to the given [`Point`].
     Drag(Point),
-    Scroll { lines: i32 },
+    /// Scroll the [`Editor`] a certain amount of lines.
+    Scroll {
+        /// The amount of lines to scroll.
+        lines: i32,
+    },
 }
 
 impl Action {
+    /// Returns whether the [`Action`] is an editing action.
     pub fn is_edit(&self) -> bool {
         matches!(self, Self::Edit(_))
     }
 }
 
+/// An action that edits text.
 #[derive(Debug, Clone, PartialEq)]
 pub enum Edit {
+    /// Insert the given character.
     Insert(char),
+    /// Paste the given text.
     Paste(Arc<String>),
+    /// Break the current line.
     Enter,
+    /// Delete the previous character.
     Backspace,
+    /// Delete the next character.
     Delete,
 }
 
+/// A cursor movement.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum Motion {
+    /// Move left.
     Left,
+    /// Move right.
     Right,
+    /// Move up.
     Up,
+    /// Move down.
     Down,
+    /// Move to the left boundary of a word.
     WordLeft,
+    /// Move to the right boundary of a word.
     WordRight,
+    /// Move to the start of the line.
     Home,
+    /// Move to the end of the line.
     End,
+    /// Move to the start of the previous window.
     PageUp,
+    /// Move to the start of the next window.
     PageDown,
+    /// Move to the start of the text.
     DocumentStart,
+    /// Move to the end of the text.
     DocumentEnd,
 }
 
 impl Motion {
+    /// Widens the [`Motion`], if possible.
     pub fn widen(self) -> Self {
         match self {
             Self::Left => Self::WordLeft,
@@ -97,6 +142,7 @@ impl Motion {
         }
     }
 
+    /// Returns the [`Direction`] of the [`Motion`].
     pub fn direction(&self) -> Direction {
         match self {
             Self::Left
@@ -115,9 +161,12 @@ impl Motion {
     }
 }
 
+/// A direction in some text.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Direction {
+    /// <-
     Left,
+    /// ->
     Right,
 }
 
diff --git a/core/src/text/highlighter.rs b/core/src/text/highlighter.rs
index 9a9cff89..a0535228 100644
--- a/core/src/text/highlighter.rs
+++ b/core/src/text/highlighter.rs
@@ -1,31 +1,48 @@
+//! Highlight text.
 use crate::Color;
 
 use std::ops::Range;
 
+/// A type capable of highlighting text.
+///
+/// A [`Highlighter`] highlights lines in sequence. When a line changes,
+/// it must be notified and the lines after the changed one must be fed
+/// again to the [`Highlighter`].
 pub trait Highlighter: 'static {
+    /// The settings to configure the [`Highlighter`].
     type Settings: PartialEq + Clone;
+
+    /// The output of the [`Highlighter`].
     type Highlight;
 
+    /// The highlight iterator type.
     type Iterator<'a>: Iterator<Item = (Range<usize>, Self::Highlight)>
     where
         Self: 'a;
 
+    /// Creates a new [`Highlighter`] from its [`Self::Settings`].
     fn new(settings: &Self::Settings) -> Self;
 
+    /// Updates the [`Highlighter`] with some new [`Self::Settings`].
     fn update(&mut self, new_settings: &Self::Settings);
 
+    /// Notifies the [`Highlighter`] that the line at the given index has changed.
     fn change_line(&mut self, line: usize);
 
+    /// Highlights the given line.
+    ///
+    /// If a line changed prior to this, the first line provided here will be the
+    /// line that changed.
     fn highlight_line(&mut self, line: &str) -> Self::Iterator<'_>;
 
+    /// Returns the current line of the [`Highlighter`].
+    ///
+    /// If `change_line` has been called, this will normally be the least index
+    /// that changed.
     fn current_line(&self) -> usize;
 }
 
-#[derive(Debug, Clone, Copy)]
-pub struct Style {
-    pub color: Color,
-}
-
+/// A highlighter that highlights nothing.
 #[derive(Debug, Clone, Copy)]
 pub struct PlainText;
 
@@ -52,9 +69,12 @@ impl Highlighter for PlainText {
     }
 }
 
+/// The format of some text.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Format<Font> {
+    /// The [`Color`] of the text.
     pub color: Option<Color>,
+    /// The `Font` of the text.
     pub font: Option<Font>,
 }