From c1ec14bed2537bb432c329754f6cb582dde4e5b3 Mon Sep 17 00:00:00 2001
From: Brendan Zabarauskas <bjzaba@yahoo.com.au>
Date: Mon, 12 May 2014 14:23:54 -0700
Subject: [PATCH] Add some helpful comments

---
 src/components/gfx/text/glyph.rs    | 25 +++++++++++++++++++++++--
 src/components/gfx/text/text_run.rs |  1 +
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/src/components/gfx/text/glyph.rs b/src/components/gfx/text/glyph.rs
index da158f1a63d..62bf4fb9f05 100644
--- a/src/components/gfx/text/glyph.rs
+++ b/src/components/gfx/text/glyph.rs
@@ -495,12 +495,32 @@ impl<'a> GlyphInfo<'a> {
     }
 }
 
-// Public data structure and API for storing and retrieving glyph data
+/// Stores the glyph data belonging to a text run.
+///
+/// Simple glyphs are stored inline in the `entry_buffer`, detailed glyphs are
+/// stored as pointers into the `detail_store`.
+///
+/// ~~~
+/// +- GlyphStore --------------------------------+
+/// |               +---+---+---+---+---+---+---+ |
+/// | entry_buffer: |   | s |   | s |   | s | s | |  d = detailed
+/// |               +-|-+---+-|-+---+-|-+---+---+ |  s = simple
+/// |                 |       |       |           |
+/// |                 |   +---+-------+           |
+/// |                 |   |                       |
+/// |               +-V-+-V-+                     |
+/// | detail_store: | d | d |                     |
+/// |               +---+---+                     |
+/// +---------------------------------------------+
+/// ~~~
 pub struct GlyphStore {
     // TODO(pcwalton): Allocation of this buffer is expensive. Consider a small-vector
     // optimization.
+    /// A buffer of glyphs within the text run, in the order in which they
+    /// appear in the input text
     entry_buffer: Vec<GlyphEntry>,
-
+    /// A store of the detailed glyph data. Detailed glyphs contained in the
+    /// `entry_buffer` point to locations in this data structure.
     detail_store: DetailedGlyphStore,
 
     is_whitespace: bool,
@@ -677,6 +697,7 @@ impl<'a> GlyphStore {
     }
 }
 
+/// An iterator over the glyphs in a character range in a `GlyphStore`.
 pub struct GlyphIterator<'a> {
     store:       &'a GlyphStore,
     char_index:  CharIndex,
diff --git a/src/components/gfx/text/text_run.rs b/src/components/gfx/text/text_run.rs
index 40620395d03..a61769cdacf 100644
--- a/src/components/gfx/text/text_run.rs
+++ b/src/components/gfx/text/text_run.rs
@@ -18,6 +18,7 @@ pub struct TextRun {
     pub font_metrics: FontMetrics,
     pub font_style: FontStyle,
     pub decoration: text_decoration::T,
+    // An Arc pointing to a Vec of Arcs?! Wat.
     pub glyphs: Arc<Vec<Arc<GlyphStore>>>,
 }