Add some class documentation to LayoutBlock

Source/core/layout/LayoutBlock.cpp

 /*
  * 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, 2011 Apple Inc. All rights reserved.
  * Copyright (C) Research In Motion Limited 2010. 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
@@ skipping 70 matching lines @@
 using namespace HTMLNames;
 
 struct SameSizeAsLayoutBlock : public LayoutBox {
     LayoutObjectChildList children;
     LineBoxList lineBoxes;
     uint32_t bitfields;
 };
 
 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 populated during layout. It is kept across layouts to handle sub-tree
+// layouts. The map could be invalidated during style change but keeping track of

[mstensho (USE GERRIT), 2015/08/31 19:28:52]

You mean "handle that we skip unchanged subtrees during layout, in such a way
that we're able to lay out deeply nested out-of-flow descendants if their
containing block got laid out"?

[Julien - ping for review, 2015/08/31 21:55:29]

Me gusta! Changed for your less hand-wavy explanation.

+// 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 update 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;
 static TrackedContainerMap* gPercentHeightContainerMap = nullptr;
 
 typedef WTF::HashSet<LayoutBlock*> DelayedUpdateScrollInfoSet;
 static int gDelayUpdateScrollInfo = 0;
 static DelayedUpdateScrollInfoSet* gDelayedUpdateScrollInfoSet = nullptr;
 
 LayoutBlock::LayoutBlock(ContainerNode* node)
@@ skipping 2804 matching lines @@
 void LayoutBlock::showLineTreeAndMark(const InlineBox* markedBox1, const char* markedLabel1, const InlineBox* markedBox2, const char* markedLabel2, const LayoutObject* obj) const
 {
     showLayoutObject();
     for (const RootInlineBox* root = firstRootBox(); root; root = root->nextRootBox())
         root->showLineTreeAndMark(markedBox1, markedLabel1, markedBox2, markedLabel2, obj, 1);
 }
 
 #endif
 
 } // namespace blink