Add basic documentation and usage example to lib.rs

parley/src/lib.rs

@@ -2,6 +2,74 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
 //! Rich text layout.
+//!
+//! Key types are:
+//! - [FontContext] and [LayoutContext] which are global resources which should be shared between all layouts (or at coarse-grained boundaries).
+//! - [FontContext] is database of fonts.
+//! - [LayoutContext] is scratch space that allows for reuse of allocations between layouts.
+//! - [RangedBuilder] and [TreeBuilder] which are builders for creating a [Layout].
+//! - [RangedBuilder] allows styles to be specified as a flat `Vec` of spans
+//! - [TreeBuilder] allows styles to be specified as a tree of spans
+//! 
+//! They are constructed using the [ranged_builder](LayoutContext::ranged_builder) and [tree_builder](LayoutContext::ranged_builder) on [LayoutContext].
+//! - [Layout] which represents styled paragraph(s) of text and can perform shaping, line-breaking, bidi-reordering, and alignment of that text.
+//! `Layout` supports re-linebreaking and re-aligning many times (in case the width at which wrapping should occur changes). But if the text content or
+//! the styles applied to that content change then a new `Layout` must be created using a new `RangedBuilder` or `TreeBuilder`.
+//!
+//! ## Usage Example
+//!
+//! See the [examples](https://github.com/linebender/parley/tree/main/examples) directory for more complete usage examples that include rendering.
+//!
+//! ```rust
+//! use parley::{
+//! Alignment, FontContext, FontWeight, InlineBox, Layout, LayoutContext, PositionedLayoutItem,
+//! StyleProperty,
+//! };
+//!
+//! // Create a FontContext (font database) and LayoutContext (scratch space).
+//! // These are both intended to be constructed rarely (perhaps even once per app):
+//! let mut font_cx = FontContext::new();
+//! let mut layout_cx = LayoutContext::new();
+//!
+//! // Create a `RangedBuilder` or a `TreeBuilder`, which are used to construct a `Layout`.
+//! const DISPLAY_SCALE : f32 = 1.0;
+//! const TEXT : &str = "Lorem Ipsum...";
+//! let mut builder = layout_cx.ranged_builder(&mut font_cx, &TEXT, DISPLAY_SCALE);
+//!
+//! // Set default styles that apply to the entire layout
+//! builder.push_default(&StyleProperty::LineHeight(1.3));
+//! builder.push_default(&StyleProperty::FontSize(16.0));
+//!
+//! // Set a style that applies to the first 4 characters
+//! builder.push(&StyleProperty::FontWeight(FontWeight::new(600.0)), 0..4);
+//!
+//! // Add a box to be laid out inline with the text
+//! builder.push_inline_box(InlineBox { id: 0, index: 5, width: 50.0, height: 50.0 });
+//!
+//! // Build the builder into a Layout
+//! let mut layout: Layout<()> = builder.build(&TEXT);
+//!
+//! // Run line-breaking and alignment on the Layout
+//! const MAX_WIDTH : Option<f32> = Some(100.0);
+//! layout.break_all_lines(MAX_WIDTH);
+//! layout.align(MAX_WIDTH, Alignment::Start);
+//!
+//! // Inspect computed layout (see examples for more details)
+//! let width = layout.width();
+//! let height = layout.height();
+//! for line in layout.lines() {
+//! for item in line.items() {
+//! match item {
+//! PositionedLayoutItem::GlyphRun(glyph_run) => {
+//! // Do something with glyph run
+//! }
+//! PositionedLayoutItem::InlineBox(inline_box) => {
+//! // So something with inline box
+//! }
+//! };
+//! }
+//! }
+//! ```
 
 // TODO: Remove this dead code allowance and hide the offending code behind the std feature gate.
 #![cfg_attr(not(feature = "std"), allow(dead_code))]