--- a/layout/generic/nsBlockReflowState.h
+++ b/layout/generic/nsBlockReflowState.h
@@ -11,36 +11,74 @@
 #include "nsFloatManager.h"
 #include "nsLineBox.h"
 #include "nsHTMLReflowState.h"
 
 class nsBlockFrame;
 class nsFrameList;
 class nsOverflowContinuationTracker;
 
-  // block reflow state flags
+// Block reflow state flags.
+//
+// BRS_UNCONSTRAINEDBSIZE is set in the nsBlockReflowState constructor when the
+// frame being reflowed has been given NS_UNCONSTRAINEDSIZE as its available
+// BSize in the nsHTMLReflowState. If set, NS_UNCONSTRAINEDSIZE is passed to
+// nsLineLayout as the available BSize.
 #define BRS_UNCONSTRAINEDBSIZE    0x00000001
-#define BRS_ISBSTARTMARGINROOT    0x00000002  // Is this frame a root for block
-#define BRS_ISBENDMARGINROOT      0x00000004  //  direction start/end margin collapsing?
-#define BRS_APPLYBSTARTMARGIN     0x00000008  // See ShouldApplyTopMargin
+// BRS_ISBSTARTMARGINROOT is set in the nsBlockReflowState constructor when
+// reflowing a "block margin root" frame (i.e. a frame with the
+// NS_BLOCK_MARGIN_ROOT flag set, for which margins apply by default).
+//
+// The flag is also set when reflowing a frame whose computed BStart border
+// padding is non-zero.
+#define BRS_ISBSTARTMARGINROOT    0x00000002
+// BRS_ISBENDMARGINROOT is set in the nsBlockReflowState constructor when
+// reflowing a "block margin root" frame (i.e. a frame with the
+// NS_BLOCK_MARGIN_ROOT flag set, for which margins apply by default).
+//
+// The flag is also set when reflowing a frame whose computed BEnd border
+// padding is non-zero.
+#define BRS_ISBENDMARGINROOT      0x00000004
+// BRS_APPLYBSTARTMARGIN is set if the BStart margin should be considered when
+// placing a linebox that contains a block frame. It may be set as a side-effect
+// of calling nsBlockFrame::ShouldApplyBStartMargin(); once set,
+// ShouldApplyBStartMargin() uses it as a fast-path way to return whether the
+// BStart margin should apply.
+//
+// If the flag hasn't been set in the block reflow state, then
+// ShouldApplyBStartMargin() will crawl the line list to see if a block frame
+// precedes the specified frame. If so, the BStart margin should be applied, and
+// the flag is set to cache the result. (If not, the BStart margin will be
+// applied as a result of the generational margin collapsing logic in
+// nsBlockReflowContext::ComputeCollapsedBStartMargin(). In this case, the flag
+// won't be set, so subsequent calls to ShouldApplyBStartMargin() will continue
+// crawl the line list.)
+//
+// This flag is also set in the nsBlockReflowState constructor if
+// BRS_ISBSTARTMARGINROOT is set; that is, the frame being reflowed is a margin
+// root by default.
+#define BRS_APPLYBSTARTMARGIN     0x00000008
 #define BRS_ISFIRSTINFLOW         0x00000010
 // Set when mLineAdjacentToTop is valid
 #define BRS_HAVELINEADJACENTTOTOP 0x00000020
 // Set when the block has the equivalent of NS_BLOCK_FLOAT_MGR
 #define BRS_FLOAT_MGR             0x00000040
 // Set when nsLineLayout::LineIsEmpty was true at the end of reflowing
 // the current line
 #define BRS_LINE_LAYOUT_EMPTY     0x00000080
 #define BRS_ISOVERFLOWCONTAINER   0x00000100
 // Our mPushedFloats list is stored on the blocks' proptable
 #define BRS_PROPTABLE_FLOATCLIST  0x00000200
 // Set when the pref layout.float-fragments-inside-column.enabled is true.
 #define BRS_FLOAT_FRAGMENTS_INSIDE_COLUMN_ENABLED 0x00000400
 #define BRS_LASTFLAG              BRS_FLOAT_FRAGMENTS_INSIDE_COLUMN_ENABLED
 
+// nsBlockReflowState contains additional reflow state information that the
+// block frame uses along with nsHTMLReflowState. Like nsHTMLReflowState, this
+// is read-only data that is passed down from a parent frame to its children.
 class nsBlockReflowState {
 public:
   nsBlockReflowState(const nsHTMLReflowState& aReflowState,
                      nsPresContext* aPresContext,
                      nsBlockFrame* aFrame,
                      bool aBStartMarginRoot, bool aBEndMarginRoot,
                      bool aBlockNeedsFloatManager,
                      nscoord aConsumedBSize = NS_INTRINSICSIZE);

--- a/layout/generic/nsFrameStateBits.h
+++ b/layout/generic/nsFrameStateBits.h
@@ -46,24 +46,26 @@
 #define FRAME_STATE_BIT(group_, value_, name_) /* nothing */
 #define DEFINED_FRAME_STATE_BIT
 #endif
 
 // == Frame state bits that apply to all frames ===============================
 
 FRAME_STATE_GROUP(Generic, nsIFrame)
 
+// This bit is set when the frame is actively being reflowed. It is set in many
+// frames' Reflow() by calling MarkInReflow() and unset in DidReflow().
 FRAME_STATE_BIT(Generic, 0, NS_FRAME_IN_REFLOW)
 
 // This bit is set when a frame is created. After it has been reflowed
 // once (during the DidReflow with a finished state) the bit is
 // cleared.
 FRAME_STATE_BIT(Generic, 1, NS_FRAME_FIRST_REFLOW)
 
-// For a continuation frame, if this bit is set, then this a "fluid" 
+// For a continuation frame, if this bit is set, then this a "fluid"
 // continuation, i.e., across a line boundary. Otherwise it's a "hard"
 // continuation, e.g. a bidi continuation.
 FRAME_STATE_BIT(Generic, 2, NS_FRAME_IS_FLUID_CONTINUATION)
 
 // For nsIAnonymousContentCreator content that's created using ContentInfo.
 FRAME_STATE_BIT(Generic, 3, NS_FRAME_ANONYMOUSCONTENTCREATOR_CONTENT)
 
 // If this bit is set, then a reference to the frame is being held
@@ -243,18 +245,18 @@ FRAME_STATE_BIT(Generic, 48, NS_FRAME_NE
 // Frame has a descendant frame that needs painting - This includes
 // cross-doc children.
 FRAME_STATE_BIT(Generic, 49, NS_FRAME_DESCENDANT_NEEDS_PAINT)
 
 // Frame is a descendant of a popup
 FRAME_STATE_BIT(Generic, 50, NS_FRAME_IN_POPUP)
 
 // Frame has only descendant frames that needs painting - This includes
-// cross-doc children. This guarantees that all descendents have 
-// NS_FRAME_NEEDS_PAINT and NS_FRAME_ALL_DESCENDANTS_NEED_PAINT, or they 
+// cross-doc children. This guarantees that all descendents have
+// NS_FRAME_NEEDS_PAINT and NS_FRAME_ALL_DESCENDANTS_NEED_PAINT, or they
 // have no display items.
 FRAME_STATE_BIT(Generic, 51, NS_FRAME_ALL_DESCENDANTS_NEED_PAINT)
 
 // Frame is marked as NS_FRAME_NEEDS_PAINT and also has an explicit
 // rect stored to invalidate.
 FRAME_STATE_BIT(Generic, 52, NS_FRAME_HAS_INVALID_RECT)
 
 // Frame is not displayed directly due to it being, or being under, an SVG
@@ -355,17 +357,17 @@ FRAME_STATE_BIT(SVG, 22, NS_STATE_SVG_PO
 //
 // Percentage values beyond the number of addressable characters, however, do
 // not influence NS_STATE_SVG_POSITIONING_MAY_USE_PERCENTAGES.  For example,
 // NS_STATE_SVG_POSITIONING_MAY_USE_PERCENTAGES would be false for:
 //
 //   <text x="10 20 30 40%">abc</text>
 //
 // NS_STATE_SVG_POSITIONING_MAY_USE_PERCENTAGES is used to determine whether
-// to recompute mPositions when the viewport size changes.  So although the 
+// to recompute mPositions when the viewport size changes.  So although the
 // first example above shows that NS_STATE_SVG_POSITIONING_MAY_USE_PERCENTAGES
 // can be true even if a viewport size change will not affect mPositions,
 // determining a completley accurate value for
 // NS_STATE_SVG_POSITIONING_MAY_USE_PERCENTAGES would require extra work that is
 // probably not worth it.
 FRAME_STATE_BIT(SVG, 23, NS_STATE_SVG_POSITIONING_MAY_USE_PERCENTAGES)
 
 FRAME_STATE_BIT(SVG, 24, NS_STATE_SVG_TEXT_IN_REFLOW)
@@ -447,28 +449,42 @@ FRAME_STATE_BIT(Text, 62, TEXT_NO_RENDER
 // (OffsetToFrameProperty)
 FRAME_STATE_BIT(Text, 63, TEXT_IN_OFFSET_CACHE)
 
 
 // == Frame state bits that apply to block frames =============================
 
 FRAME_STATE_GROUP(Block, nsBlockFrame)
 
-// See the meanings at http://www-archive.mozilla.org/newlayout/doc/block-and-line.html
-
 // Something in the block has changed that requires Bidi resolution to be
-// performed on the block. This flag must be either set on all blocks in a 
+// performed on the block. This flag must be either set on all blocks in a
 // continuation chain or none of them.
 FRAME_STATE_BIT(Block, 20, NS_BLOCK_NEEDS_BIDI_RESOLUTION)
 
 FRAME_STATE_BIT(Block, 21, NS_BLOCK_HAS_PUSHED_FLOATS)
+
+// This indicates that this is a frame from which child margins can be
+// calculated. The absence of this flag implies that child margin calculations
+// should ignore the frame and look further up the parent chain. Used in
+// nsBlockReflowContext::ComputeCollapsedBStartMargin() via
+// nsBlockFrame::IsMarginRoot().
+//
+// This causes the nsBlockReflowState's constructor to set the
+// BRS_ISBSTARTMARGINROOT and BRS_ISBENDMARGINROOT flags.
 FRAME_STATE_BIT(Block, 22, NS_BLOCK_MARGIN_ROOT)
+
+// This indicates that a block frame should create its own float manager. This
+// is required by each block frame that can contain floats. The float manager is
+// used to reserve space for the floated frames.
 FRAME_STATE_BIT(Block, 23, NS_BLOCK_FLOAT_MGR)
+
 FRAME_STATE_BIT(Block, 24, NS_BLOCK_HAS_LINE_CURSOR)
+
 FRAME_STATE_BIT(Block, 25, NS_BLOCK_HAS_OVERFLOW_LINES)
+
 FRAME_STATE_BIT(Block, 26, NS_BLOCK_HAS_OVERFLOW_OUT_OF_FLOWS)
 
 // Set on any block that has descendant frames in the normal
 // flow with 'clear' set to something other than 'none'
 // (including <BR CLEAR="..."> frames)
 FRAME_STATE_BIT(Block, 27, NS_BLOCK_HAS_CLEAR_CHILDREN)
 
 // NS_BLOCK_CLIP_PAGINATED_OVERFLOW is only set in paginated prescontexts, on

--- a/layout/generic/nsLineLayout.h
+++ b/layout/generic/nsLineLayout.h
@@ -494,23 +494,45 @@ protected:
     {
       return mJustificationInfo.mIsEndJustifiable;
     }
 
     bool ParticipatesInJustification() const;
   };
   PerFrameData* mFrameFreeList;
 
+  // In nsLineLayout, a "span" is a container inline frame, and a "frame" is one
+  // of its children.
+  //
+  // nsLineLayout::BeginLineReflow() creates the initial PerSpanData which is
+  // called the "root span". nsInlineFrame::ReflowFrames() creates a new
+  // PerSpanData when it calls nsLineLayout::BeginSpan(); at this time, the
+  // nsLineLayout object's mCurrentSpan is switched to the new span. The new
+  // span records the old mCurrentSpan as its parent. After reflowing the child
+  // inline frames, nsInlineFrame::ReflowFrames() calls nsLineLayout::EndSpan(),
+  // which pops the PerSpanData and re-sets mCurrentSpan.
   struct PerSpanData {
     union {
       PerSpanData* mParent;
       PerSpanData* mNextFreeSpan;
     };
+
+    // The PerFrameData of the inline frame that "owns" the span, or null if
+    // this is the root span. mFrame is initialized to the containing inline
+    // frame's PerFrameData when a new PerSpanData is pushed in
+    // nsLineLayout::BeginSpan().
     PerFrameData* mFrame;
+
+    // The first PerFrameData structure in the span.
     PerFrameData* mFirstFrame;
+
+    // The last PerFrameData structure in the span. PerFrameData structures are
+    // added to the span as they are reflowed. mLastFrame may also be directly
+    // manipulated if a line is split, or if frames are pushed from one line to
+    // the next.
     PerFrameData* mLastFrame;
 
     const nsHTMLReflowState* mReflowState;
     bool mNoWrap;
     mozilla::WritingMode mWritingMode;
     bool mContainsFloat;
     bool mHasNonemptyContent;