Write documentation for the new text APIs

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();