Add documentation to 2 DeprecatedPaintLayer objects

Source/core/paint/DeprecatedPaintLayerStackingNodeIterator.h

Index: Source/core/paint/DeprecatedPaintLayerStackingNodeIterator.h
diff --git a/Source/core/paint/DeprecatedPaintLayerStackingNodeIterator.h b/Source/core/paint/DeprecatedPaintLayerStackingNodeIterator.h
index cc5d209e69a5dc6c507483c02ae64929e0f50276..6dde5f8918d0c2595b2c77d8648e337f5416ebd7 100644
--- a/Source/core/paint/DeprecatedPaintLayerStackingNodeIterator.h
+++ b/Source/core/paint/DeprecatedPaintLayerStackingNodeIterator.h
@@ -38,6 +38,10 @@ namespace blink {
 
 enum ChildrenIteration {
     NegativeZOrderChildren = 1,
+    // Normal flow children are not mandated by CSS 2.1 but are an artifact of
+    // our implementation: we allocate DeprecatedPaintLayers for elements that
+    // are not treated as stacking contexts and thus we need to walk them

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

I don't think "stacking contexts" is the right term here. What's the grown-up
word to use for "positioned object and/or stacking context"? "Stacking node"?
<div style="position:absolute;"> would be a stacking node, but not a stacking
context. <div style="overflow:hidden;"> would be neither. <div
style="opacity:0.5;"> would be a stacking node AND a stacking context, likewise
for <div style="position:absolute; z-index:7;">.

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

The CSS word for stacking context + positioned is "treated as stacking context"
(see the infamous appendix E). It does include floats too in CSS lingo but
that's because we implement the painting algorithm in a different way.

[mstensho (USE GERRIT), 2015/09/04 13:22:32]

OK. Lacking a better word for a true stacking context (one that orders
positioned descendants and true stacking context descendants), I can live with
the current wording.

I think of a (true) stacking context as something with applicable z-index,
opacity or transform (anything else? Rhetorical question to my lazy self, who
doesn't bother to check for other things). A stacking context paints its
background, foreground and floats atomically (so that no other elements on the
outside can interleave), and controls the paint order of descendant (true)
stacking contexts AND positioned descendants.

The "treated as stacking context" thing is only about painting background,
foreground and floats atomically.

+    // during painting and hit-testing.
     NormalFlowChildren = 1 << 1,
     PositiveZOrderChildren = 1 << 2,
     AllChildren = NegativeZOrderChildren | NormalFlowChildren | PositiveZOrderChildren