Add some class documentation to LayoutBlock

Source/core/layout/LayoutBlock.cpp

Index: Source/core/layout/LayoutBlock.cpp
diff --git a/Source/core/layout/LayoutBlock.cpp b/Source/core/layout/LayoutBlock.cpp
index 019e3cf68a705528bc7fad606dd03984414ad849..8ded83dd2346abfffd68c882e11c6337ce54ab02 100644
--- a/Source/core/layout/LayoutBlock.cpp
+++ b/Source/core/layout/LayoutBlock.cpp
@@ -88,7 +88,18 @@ struct SameSizeAsLayoutBlock : public LayoutBox {
 
 static_assert(sizeof(LayoutBlock) == sizeof(SameSizeAsLayoutBlock), "LayoutBlock should stay small");
 
+// This map keeps track of the positioned objects associated with a containing block.
+//
+// This map is cleared at the beginning of layout and populated during layout. The map

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

It is populated during layout, but it's not cleared at the beginning of layout.
How would we be able to add everything back then, without doing a full subtree
layout?

<div id="a" style="position:relative;">
  <div id="b" style="width:100px;">
    <div id="extra">
       <div id="c" style="position:absolute;">

So #a has a map that contains #c.

Now imagine that we change the "width" property of #a, which will trigger a
relayout. If we cleared the map of positioned descendants of #a when starting
layout of #a, we'd not add #c back into the map, since we may skip layout of
#b's children, since #b doesn't change, having a fixed width.

Note: To demonstrate my point, we need #extra because of the layoutChildren flag
in the layoutFoo() methods. It will be set when laying out the the children of
#a, so that we'll actually force layout out #b (quite unnecessarily so, as far
as I can tell), and walk #b's children, but not necessarily lay them out.

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

Indeed, my bad for not checking thoroughly. I have updated this line to be
(emphasis mine):

// This map is populated during layout. It is kept across layouts to handle
sub-tree
// layouts. [...]
// it's easier to just *update* it for every layout.

+// could be invalidated during style change but keeping track of containing blocks at
+// that time is complicated (we are in the middle of recomputing the style so we can't
+// rely on any of its information), which is why it's easier to just recompute it for
+// every layout.
 static TrackedDescendantsMap* gPositionedDescendantsMap = nullptr;
+
+// This map keeps track of the descendants whose 'height' is percentage associated
+// with a containing block. Like |gPositionedDescendantsMap|, it is also recomputed
+// for every layout (see the comment above about why).
 static TrackedDescendantsMap* gPercentHeightDescendantsMap = nullptr;
 
 static TrackedContainerMap* gPositionedContainerMap = nullptr;