Update documentation

src/buffer.rs

@@ -12,9 +12,9 @@ use crate::{Attrs, AttrsList, Color, FontSystem, LayoutGlyph, LayoutLine, ShapeL
 /// An action to perform on a [TextBuffer]
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub enum TextAction {
-    /// Move cursor to previous character ([Left] in LTR, [Right] in RTL)
+    /// Move cursor to previous character ([Self::Left] in LTR, [Self::Right] in RTL)
     Previous,
-    /// Move cursor to next character ([Right] in LTR, [Left] in RTL)
+    /// Move cursor to next character ([Self::Right] in LTR, [Self::Left] in RTL)
     Next,
     /// Move cursor left
     Left,
@@ -58,6 +58,7 @@ pub struct TextCursor {
 }
 
 impl TextCursor {
+    /// Create a new cursor
     pub const fn new(line: usize, index: usize) -> Self {
         Self { line, index }
     }
@@ -75,6 +76,7 @@ impl TextLayoutCursor {
     }
 }
 
+/// A line of visible text for rendering
 pub struct TextLayoutRun<'a> {
     /// The index of the original text line
     pub line_i: usize,
@@ -88,6 +90,7 @@ pub struct TextLayoutRun<'a> {
     pub line_y: i32,
 }
 
+/// An iterator of visible text lines, see [TextLayoutRun]
 pub struct TextLayoutRunIter<'a, 'b> {
     buffer: &'b TextBuffer<'a>,
     line_i: usize,

src/layout.rs

@@ -3,6 +3,7 @@
 use crate::{CacheKey, Color};
 
 /// A laid out glyph
+#[derive(Debug)]
 pub struct LayoutGlyph {
     /// Start index of cluster in original line
     pub start: usize,

src/lib.rs

@@ -1,5 +1,51 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
+//! # COSMIC Text
+//!
+//! This library provides advanced text handling in a generic way. It provides abstractions for
+//! shaping, font discovery, font fallback, layout, rasterization, and editing. Shaping utilizes
+//! rustybuzz, font discovery utilizes fontdb, and the rasterization is optional and utilizes
+//! swash. The other features are developed internal to this library.
+//!
+//! It is recommended that you start by creating a [FontSystem], after which you can create a
+//! [TextBuffer], provide it with some text, and then inspect the layout it produces. At this
+//! point, you can use the `SwashCache` to rasterize glyphs into either images or pixels.
+//!
+//! ```
+//! use cosmic_text::{Attrs, FontSystem, SwashCache, TextBuffer, TextMetrics};
+//!
+//! // A FontSystem provides access to detected system fonts, create one per application
+//! let font_system = FontSystem::new();
+//!
+//! // A SwashCache stores rasterized glyphs, create one per application
+//! let mut swash_cache = SwashCache::new(&font_system);
+//!
+//! // Text metrics indicate the font size and line height of a buffer
+//! let metrics = TextMetrics::new(14, 20);
+//!
+//! // A TextBuffer provides shaping and layout for a UTF-8 string, create one per text widget
+//! let mut text_buffer = TextBuffer::new(&font_system, metrics);
+//!
+//! // Set a size for the text buffer, in pixels
+//! text_buffer.set_size(80, 25);
+//!
+//! // Attributes indicate what font to choose
+//! let attrs = Attrs::new();
+//!
+//! // Add some text!
+//! text_buffer.set_text("Hello, Rust! 🦀\n", attrs);
+//!
+//! // Perform shaping as desired
+//! text_buffer.shape_until_scroll();
+//!
+//! // Inspect the output runs
+//! for run in text_buffer.layout_runs() {
+//!     for glyph in run.glyphs.iter() {
+//!         println!("{:#?}", glyph);
+//!     }
+//! }
+//! ```
+
 pub use self::attrs::*;
 mod attrs;