Add some class documentation to LayoutBlock

Source/core/layout/LayoutBlock.h

 /*
  * Copyright (C) 1999 Lars Knoll (knoll@kde.org)
  *           (C) 1999 Antti Koivisto (koivisto@kde.org)
  *           (C) 2007 David Smith (catfish.man@gmail.com)
  * Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Apple Inc. All rights reserved.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
  * License as published by the Free Software Foundation; either
  * version 2 of the License, or (at your option) any later version.
@@ skipping 31 matching lines @@
 class LayoutInline;
 class WordMeasurement;
 
 typedef WTF::ListHashSet<LayoutBox*, 16> TrackedLayoutBoxListHashSet;
 typedef WTF::HashMap<const LayoutBlock*, OwnPtr<TrackedLayoutBoxListHashSet>> TrackedDescendantsMap;
 typedef WTF::HashMap<const LayoutBox*, OwnPtr<HashSet<LayoutBlock*>>> TrackedContainerMap;
 typedef Vector<WordMeasurement, 64> WordMeasurements;
 
 enum ContainingBlockState { NewContainingBlock, SameContainingBlock };
 
+// LayoutBlock is the class that is used by any LayoutObject
+// that is a containing block.
+// 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.
+//
+// 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().
+//
+// 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;
 
 protected:
     explicit LayoutBlock(ContainerNode*);
     ~LayoutBlock() override;
 
 public:
     LayoutObject* firstChild() const { ASSERT(children() == virtualChildren()); return children()->firstChild(); }
@@ skipping 359 matching lines @@
     // FIXME: This is temporary as we move code that accesses block flow
     // member variables out of LayoutBlock and into LayoutBlockFlow.
     friend class LayoutBlockFlow;
 };
 
 DEFINE_LAYOUT_OBJECT_TYPE_CASTS(LayoutBlock, isLayoutBlock());
 
 } // namespace blink
 
 #endif // LayoutBlock_h