Add documentation to 2 DeprecatedPaintLayer objects

Source/core/paint/DeprecatedPaintLayerStackingNode.h

Index: Source/core/paint/DeprecatedPaintLayerStackingNode.h
diff --git a/Source/core/paint/DeprecatedPaintLayerStackingNode.h b/Source/core/paint/DeprecatedPaintLayerStackingNode.h
index d4b0150ca1e833351e9e4222832cacb55e4e7a24..5e7220e364d5eea095acd1cdc266b5221d8ecc6d 100644
--- a/Source/core/paint/DeprecatedPaintLayerStackingNode.h
+++ b/Source/core/paint/DeprecatedPaintLayerStackingNode.h
@@ -58,6 +58,28 @@ class DeprecatedPaintLayerCompositor;
 class ComputedStyle;
 class LayoutBoxModelObject;
 
+// DeprecatedPaintLayerStackingNode represents anything that is treated as a
+// stacking context.
+//
+// Stacking contexts are the basis for the CSS painting algorithm. The paint
+// order is determined by walking stacking contexts (or elements treated like a
+// stacking context like positioned objects or floats) in an order defined by
+// ‘z-index’. This walk is interleaved with content that is not a stacking.
+// context. See CSS 2.1 appendix e for the actual algorithm

[mstensho (USE GERRIT), 2015/09/01 18:59:06]

Might want to capitalize that "e".

[Julien - ping for review, 2015/09/03 14:25:54]

D-O-N-E!

+// http://www.w3.org/TR/CSS21/zindex.html
+// See also DeprecatedPaintLayerPainter (in particular paintLayerContents) for
+// our implementation of the walk.
+//
+// Stacking contexts form a subtree over the layout tree. Ideally we would want
+// this class to be a node in this tree but there are potential issues with

[mstensho (USE GERRIT), 2015/09/01 18:59:06]

"objects of this class to be nodes in this tree"?

[Julien - ping for review, 2015/09/03 14:25:54]

sgtm.

+// stale pointers so we rely on DeprecatedPaintLayer's tree structure.
+//
+// This class's purpose is to cache the z-order lists for painting and

[eae, 2015/09/01 18:08:59]

They're used to represent and not just cache the stacking contexts, right?

[Julien - ping for review, 2015/09/03 14:25:54]

Good catch. Amended the description of the class to be better aligned with that:

// This class's purpose is to represent a node in the stacking context tree
// (aka paint tree). It currently caches the z-order lists for painting and
// hit-testing.

+// hit-testing.
+//
+// To implement any zorder list iterations, use

[mstensho (USE GERRIT), 2015/09/01 18:59:06]

"z-order"

[Julien - ping for review, 2015/09/03 14:25:54]

changed.

+// DeprecatedPaintLayerStackingNodeIterator and
+// DeprecatedPaintLayerStackingNodeReverseIterator.
 class CORE_EXPORT DeprecatedPaintLayerStackingNode {
     WTF_MAKE_FAST_ALLOCATED(DeprecatedPaintLayerStackingNode);
     WTF_MAKE_NONCOPYABLE(DeprecatedPaintLayerStackingNode);