Bug 1273049 - Migrate documentation in block-and-line.html into the tree. r=dholbert

I also adjust some of the old flag name to their logical name, and
rewrite some of the content where I see fit.

MozReview-Commit-ID: 7wAsDUOiN0a

--HG--
extra : rebase_source : 18e28e5ed1c593fb272042508b36244f132da4f5

layout/generic/nsBlockReflowState.h

@@ -16,11 +16,46 @@ 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
@@ -36,6 +71,9 @@ class nsOverflowContinuationTracker;
 #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,

layout/generic/nsFrameStateBits.h

@@ -51,6 +51,8 @@
 
 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
@@ -452,18 +454,32 @@ FRAME_STATE_BIT(Text, 63, TEXT_IN_OFFSET_CACHE)
 
 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
 // 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

layout/generic/nsLineLayout.h

@@ -499,13 +499,35 @@ protected:
   };
   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;