Write documentation for the new text APIs

5 files changed, 59 insertions, 1 deletions

diff --git a/graphics/src/lib.rs b/graphics/src/lib.rs
index a0729058..7a213909 100644
--- a/graphics/src/lib.rs
+++ b/graphics/src/lib.rs
@@ -10,7 +10,7 @@
 #![forbid(rust_2018_idioms)]
 #![deny(
     missing_debug_implementations,
-    //missing_docs,
+    missing_docs,
     unsafe_code,
     unused_results,
     rustdoc::broken_intra_doc_links
diff --git a/graphics/src/text.rs b/graphics/src/text.rs
index c10eacad..7261900e 100644
--- a/graphics/src/text.rs
+++ b/graphics/src/text.rs
@@ -1,3 +1,4 @@
+//! Draw text.
 pub mod cache;
 pub mod editor;
 pub mod paragraph;
@@ -17,6 +18,7 @@ use once_cell::sync::OnceCell;
 use std::borrow::Cow;
 use std::sync::{Arc, RwLock};
 
+/// Returns the global [`FontSystem`].
 pub fn font_system() -> &'static RwLock<FontSystem> {
     static FONT_SYSTEM: OnceCell<RwLock<FontSystem>> = OnceCell::new();
 
@@ -32,6 +34,7 @@ pub fn font_system() -> &'static RwLock<FontSystem> {
     })
 }
 
+/// A set of system fonts.
 #[allow(missing_debug_implementations)]
 pub struct FontSystem {
     raw: cosmic_text::FontSystem,
@@ -39,10 +42,12 @@ pub struct FontSystem {
 }
 
 impl FontSystem {
+    /// Returns the raw [`cosmic_text::FontSystem`].
     pub fn raw(&mut self) -> &mut cosmic_text::FontSystem {
         &mut self.raw
     }
 
+    /// Loads a font from its bytes.
     pub fn load_font(&mut self, bytes: Cow<'static, [u8]>) {
         let _ = self.raw.db_mut().load_font_source(
             cosmic_text::fontdb::Source::Binary(Arc::new(bytes.into_owned())),
@@ -51,14 +56,19 @@ impl FontSystem {
         self.version = Version(self.version.0 + 1);
     }
 
+    /// Returns the current [`Version`] of the [`FontSystem`].
+    ///
+    /// Loading a font will increase the version of a [`FontSystem`].
     pub fn version(&self) -> Version {
         self.version
     }
 }
 
+/// A version number.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
 pub struct Version(u32);
 
+/// Measures the dimensions of the given [`cosmic_text::Buffer`].
 pub fn measure(buffer: &cosmic_text::Buffer) -> Size {
     let (width, total_lines) = buffer
         .layout_runs()
@@ -69,6 +79,7 @@ pub fn measure(buffer: &cosmic_text::Buffer) -> Size {
     Size::new(width, total_lines as f32 * buffer.metrics().line_height)
 }
 
+/// Returns the attributes of the given [`Font`].
 pub fn to_attributes(font: Font) -> cosmic_text::Attrs<'static> {
     cosmic_text::Attrs::new()
         .family(to_family(font.family))
@@ -124,6 +135,7 @@ fn to_style(style: font::Style) -> cosmic_text::Style {
     }
 }
 
+/// Converts some [`Shaping`] strategy to a [`cosmic_text::Shaping`] strategy.
 pub fn to_shaping(shaping: Shaping) -> cosmic_text::Shaping {
     match shaping {
         Shaping::Basic => cosmic_text::Shaping::Basic,
@@ -131,6 +143,7 @@ pub fn to_shaping(shaping: Shaping) -> cosmic_text::Shaping {
     }
 }
 
+/// Converts some [`Color`] to a [`cosmic_text::Color`].
 pub fn to_color(color: Color) -> cosmic_text::Color {
     let [r, g, b, a] = color::pack(color).components();
 
diff --git a/graphics/src/text/cache.rs b/graphics/src/text/cache.rs
index 577c4687..b3293dd4 100644
--- a/graphics/src/text/cache.rs
+++ b/graphics/src/text/cache.rs
@@ -1,3 +1,4 @@
+//! Cache text.
 use crate::core::{Font, Size};
 use crate::text;
 
@@ -5,6 +6,7 @@ use rustc_hash::{FxHashMap, FxHashSet};
 use std::collections::hash_map;
 use std::hash::{BuildHasher, Hash, Hasher};
 
+/// A store of recently used sections of text.
 #[allow(missing_debug_implementations)]
 #[derive(Default)]
 pub struct Cache {
@@ -21,14 +23,17 @@ type HashBuilder = twox_hash::RandomXxHashBuilder64;
 type HashBuilder = std::hash::BuildHasherDefault<twox_hash::XxHash64>;
 
 impl Cache {
+    /// Creates a new empty [`Cache`].
     pub fn new() -> Self {
         Self::default()
     }
 
+    /// Gets the text [`Entry`] with the given [`KeyHash`].
     pub fn get(&self, key: &KeyHash) -> Option<&Entry> {
         self.entries.get(key)
     }
 
+    /// Allocates a text [`Entry`] if it is not already present in the [`Cache`].
     pub fn allocate(
         &mut self,
         font_system: &mut cosmic_text::FontSystem,
@@ -88,6 +93,9 @@ impl Cache {
         (hash, self.entries.get_mut(&hash).unwrap())
     }
 
+    /// Trims the [`Cache`].
+    ///
+    /// This will clear the sections of text that have not been used since the last `trim`.
     pub fn trim(&mut self) {
         self.entries
             .retain(|key, _| self.recently_used.contains(key));
@@ -99,13 +107,20 @@ impl Cache {
     }
 }
 
+/// A cache key representing a section of text.
 #[derive(Debug, Clone, Copy)]
 pub struct Key<'a> {
+    /// The content of the text.
     pub content: &'a str,
+    /// The size of the text.
     pub size: f32,
+    /// The line height of the text.
     pub line_height: f32,
+    /// The [`Font`] of the text.
     pub font: Font,
+    /// The bounds of the text.
     pub bounds: Size,
+    /// The shaping strategy of the text.
     pub shaping: text::Shaping,
 }
 
@@ -123,10 +138,14 @@ impl Key<'_> {
     }
 }
 
+/// The hash of a [`Key`].
 pub type KeyHash = u64;
 
+/// A cache entry.
 #[allow(missing_debug_implementations)]
 pub struct Entry {
+    /// The buffer of text, ready for drawing.
     pub buffer: cosmic_text::Buffer,
+    /// The minimum bounds of the text.
     pub min_bounds: Size,
 }
diff --git a/graphics/src/text/editor.rs b/graphics/src/text/editor.rs
index a05312dc..d5262ae8 100644
--- a/graphics/src/text/editor.rs
+++ b/graphics/src/text/editor.rs
@@ -1,3 +1,4 @@
+//! Draw and edit text.
 use crate::core::text::editor::{
     self, Action, Cursor, Direction, Edit, Motion,
 };
@@ -11,6 +12,7 @@ use cosmic_text::Edit as _;
 use std::fmt;
 use std::sync::{self, Arc};
 
+/// A multi-line text editor.
 #[derive(Debug, PartialEq)]
 pub struct Editor(Option<Arc<Internal>>);
 
@@ -23,14 +25,21 @@ struct Internal {
 }
 
 impl Editor {
+    /// Creates a new empty [`Editor`].
     pub fn new() -> Self {
         Self::default()
     }
 
+    /// Returns the buffer of the [`Editor`].
     pub fn buffer(&self) -> &cosmic_text::Buffer {
         self.internal().editor.buffer()
     }
 
+    /// Creates a [`Weak`] reference to the [`Editor`].
+    ///
+    /// This is useful to avoid cloning the [`Editor`] when
+    /// referential guarantees are unnecessary. For instance,
+    /// when creating a rendering tree.
     pub fn downgrade(&self) -> Weak {
         let editor = self.internal();
 
@@ -662,13 +671,16 @@ impl fmt::Debug for Internal {
     }
 }
 
+/// A weak reference to an [`Editor`].
 #[derive(Debug, Clone)]
 pub struct Weak {
     raw: sync::Weak<Internal>,
+    /// The bounds of the [`Editor`].
     pub bounds: Size,
 }
 
 impl Weak {
+    /// Tries to update the reference into an [`Editor`].
     pub fn upgrade(&self) -> Option<Editor> {
         self.raw.upgrade().map(Some).map(Editor)
     }
diff --git a/graphics/src/text/paragraph.rs b/graphics/src/text/paragraph.rs
index d0396e8e..ccfe4a61 100644
--- a/graphics/src/text/paragraph.rs
+++ b/graphics/src/text/paragraph.rs
@@ -1,3 +1,4 @@
+//! Draw paragraphs.
 use crate::core;
 use crate::core::alignment;
 use crate::core::text::{Hit, LineHeight, Shaping, Text};
@@ -7,6 +8,7 @@ use crate::text;
 use std::fmt;
 use std::sync::{self, Arc};
 
+/// A bunch of text.
 #[derive(Clone, PartialEq)]
 pub struct Paragraph(Option<Arc<Internal>>);
 
@@ -23,14 +25,21 @@ struct Internal {
 }
 
 impl Paragraph {
+    /// Creates a new empty [`Paragraph`].
     pub fn new() -> Self {
         Self::default()
     }
 
+    /// Returns the buffer of the [`Paragraph`].
     pub fn buffer(&self) -> &cosmic_text::Buffer {
         &self.internal().buffer
     }
 
+    /// Creates a [`Weak`] reference to the [`Paragraph`].
+    ///
+    /// This is useful to avoid cloning the [`Editor`] when
+    /// referential guarantees are unnecessary. For instance,
+    /// when creating a rendering tree.
     pub fn downgrade(&self) -> Weak {
         let paragraph = self.internal();
 
@@ -269,15 +278,20 @@ impl Default for Internal {
     }
 }
 
+/// A weak reference to a [`Paragraph`].
 #[derive(Debug, Clone)]
 pub struct Weak {
     raw: sync::Weak<Internal>,
+    /// The minimum bounds of the [`Paragraph`].
     pub min_bounds: Size,
+    /// The horizontal alignment of the [`Paragraph`].
     pub horizontal_alignment: alignment::Horizontal,
+    /// The vertical alignment of the [`Paragraph`].
     pub vertical_alignment: alignment::Vertical,
 }
 
 impl Weak {
+    /// Tries to update the reference into a [`Paragraph`].
     pub fn upgrade(&self) -> Option<Paragraph> {
         self.raw.upgrade().map(Some).map(Paragraph)
     }