diff --git a/parley/src/context.rs b/parley/src/context.rs
index 2b1e82b0..418ed34d 100644
--- a/parley/src/context.rs
+++ b/parley/src/context.rs
@@ -20,7 +20,9 @@ use swash::text::cluster::CharInfo;
 use crate::builder::TreeBuilder;
 use crate::inline_box::InlineBox;
 
-/// Shared scratch space used when constructing text layouts
+/// Shared scratch space used when constructing text layouts.
+///
+/// This type is designed to be a global resource with only one per-application (or per-thread).
 pub struct LayoutContext<B: Brush = [u8; 4]> {
     pub(crate) bidi: bidi::BidiResolver,
     pub(crate) rcx: ResolveContext,
diff --git a/parley/src/font.rs b/parley/src/font.rs
index 97e790bc..1dc41870 100644
--- a/parley/src/font.rs
+++ b/parley/src/font.rs
@@ -6,9 +6,9 @@ use fontique::Collection;
 #[cfg(feature = "std")]
 use fontique::SourceCache;
 
-/// A font database/cache (wrapper around a the [fontique] crate)
+/// A font database/cache (wrapper around a Fontique [`Collection`] and [`SourceCache`]).
 ///
-/// This type is designed to be a global resource with only one per-application (or per-thread)
+/// This type is designed to be a global resource with only one per-application (or per-thread).
 #[derive(Default)]
 pub struct FontContext {
     pub collection: Collection,
@@ -17,6 +17,7 @@ pub struct FontContext {
 }
 
 impl FontContext {
+    /// Create a new `FontContext`, discovering system fonts if available.
     pub fn new() -> Self {
         Default::default()
     }
diff --git a/parley/src/lib.rs b/parley/src/lib.rs
index 127f3359..40f1585d 100644
--- a/parley/src/lib.rs
+++ b/parley/src/lib.rs
@@ -1,9 +1,9 @@
 // Copyright 2021 the Parley Authors
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
-//! Parley is library for rich text layout.
+//! Parley is a library for rich text layout.
 //!
-//! Key types are:
+//! Some key types are:
 //! - [`FontContext`] and [`LayoutContext`] are resources which should be shared globally (or at coarse-grained boundaries).
 //!   - [`FontContext`] is database of fonts.
 //!   - [`LayoutContext`] is scratch space that allows for reuse of allocations between layouts.
@@ -11,8 +11,8 @@
 //!     - [`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.
+//!   They are constructed using the [`ranged_builder`](LayoutContext::ranged_builder) and [`tree_builder`](LayoutContext::ranged_builder) methods 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`.
@@ -62,10 +62,10 @@
 //!     for item in line.items() {
 //!         match item {
 //!             PositionedLayoutItem::GlyphRun(glyph_run) => {
-//!                 // Do something with  glyph run
+//!                 // Render the glyph run
 //!             }
 //!             PositionedLayoutItem::InlineBox(inline_box) => {
-//!                 // So something with inline box
+//!                 // Render the inline box
 //!             }
 //!         };
 //!     }