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 35 matching lines @@
 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 };
 
 typedef WTF::HashMap<LayoutBlock*, OwnPtr<ListHashSet<LayoutInline*>>> ContinuationOutlineTableMap;
 
 ContinuationOutlineTableMap* continuationOutlineTable();
 
+// 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

[wkorman, 2015/08/28 22:01:17]

What's the best spec to link to in general, for my knowledge for future similar
docs? The most recent, or the most finalized/official-recommendation, or the
first spec that was finalized that has the definition in question?

Asking because here we link to the official recommendation spec, but for similar
in prior change we linked to an "editor's draft" of css3 though we were
describing a css2.1 notion of intrinsic size:

https://drafts.csswg.org/css-sizing-3/#intrinsic

and atop this it has a link to the "latest version" which is a "working draft":

http://www.w3.org/TR/css3-sizing/

+// 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;
 
 protected:
     explicit LayoutBlock(ContainerNode*);
     ~LayoutBlock() override;
 
 public:
     LayoutObject* firstChild() const { ASSERT(children() == virtualChildren()); return children()->firstChild(); }
@@ skipping 364 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