Add some class documentation to LayoutBlock

Source/core/layout/LayoutBlock.h

Index: Source/core/layout/LayoutBlock.h
diff --git a/Source/core/layout/LayoutBlock.h b/Source/core/layout/LayoutBlock.h
index d89e5f764eab71009d0160a7c66521f18644c01a..8e9fbd9175cc07078ad27a617c37100c3a6e08c3 100644
--- a/Source/core/layout/LayoutBlock.h
+++ b/Source/core/layout/LayoutBlock.h
@@ -53,6 +53,47 @@ typedef WTF::HashMap<LayoutBlock*, OwnPtr<ListHashSet<LayoutInline*>>> Continuat
 
 ContinuationOutlineTableMap* continuationOutlineTable();
 
+// LayoutBlock is the class that is used by any LayoutObject
+// that is a containing block.

[mstensho (USE GERRIT), 2015/08/31 12:00:45]

Close enough, I guess, but this isn't true for positioned inlines
(LayoutInline), which also establish a containing block for absolutely
positioned descendants.

[Julien - ping for review, 2015/08/31 18:08:30]

CSS makes me sad. They call positioned inlines a containing block as you rightly
point out (see section 10.1.4) but it's not even a block. Added the following to
clarify:

// CSS is inconsistent and allows inline elements (LayoutInline) to be
// containing blocks, even though they are not blocks. Our
// implementation is as confused with inlines. See e.g.
// LayoutObject::containingBlock() vs LayoutObject::container().

+// http://www.w3.org/TR/CSS2/visuren.html#containing-block
+// See also LayoutObject::containingBlock() that is the
+// function used to get the containing block of a LayoutObject.
+//
+// Containing blocks are a central concept for layout, in
+// particular to the layout of out-of-flow positioned
+// elements. They are used to determine the sizing as well
+// as the positioning of the LayoutObjects.
+//
+// Out-of-flow positioned elements are laid out by their
+// containing blocks so LayoutBlock keeps track of them
+// through |gPositionedDescendantsMap| (see LayoutBlock.cpp).
+// See LayoutBlock::layoutPositionedObjects() for the logic
+// to lay them out.
+//
+//
+// ***** HANDLING OUT-OF-FLOW POSITIONED OBJECTS *****
+// Care should be taken to handle out-of-flow positioned objects during
+// certain tree walks (e.g. layout()). The rule is that anything that
+// cares about containing blocks should skip the out-of-flow elements
+// in the normal tree walk and do an optional follow-up pass for them
+// using LayoutBlock::positionedObjects().
+// Not doing so will result in passing the wrong containing
+// block as tree walks will always pass the parent as the
+// containing block.
+//
+// Sample code of how to handle positioned objects in LayoutBlock:
+//
+// for (LayoutObject* child = firstChild(); child; child = child->nextSibling()) {
+//     if (child->isOutOfFlowPositioned())
+//         continue;
+//
+//     // Handle normal flow children.
+//     ...
+// }
+// for (LayoutObject positionedObject : positionedObjects()) {
+//     // Handle out-of-flow positioned objects.
+//     ...
+// }
 class CORE_EXPORT LayoutBlock : public LayoutBox {
 public:
     friend class LineLayoutState;