Add documentation to 2 DeprecatedPaintLayer objects

Source/core/paint/DeprecatedPaintLayerStackingNodeIterator.h

 /*
  * Copyright (C) 2013 Google Inc. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
  * met:
  *
  *     * Redistributions of source code must retain the above copyright
  * notice, this list of conditions and the following disclaimer.
  *     * Redistributions in binary form must reproduce the above
@@ skipping 20 matching lines @@
 #ifndef DeprecatedPaintLayerStackingNodeIterator_h
 #define DeprecatedPaintLayerStackingNodeIterator_h
 
 #include "wtf/Allocator.h"
 #include "wtf/Noncopyable.h"
 
 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
 };
 
 class DeprecatedPaintLayerStackingNode;
 class DeprecatedPaintLayer;
 
 // This iterator walks the DeprecatedPaintLayerStackingNode lists in the following order:
 // NegativeZOrderChildren -> NormalFlowChildren -> PositiveZOrderChildren.
@@ skipping 32 matching lines @@
 
     const DeprecatedPaintLayerStackingNode& m_root;
     unsigned m_remainingChildren;
     int m_index;
     DeprecatedPaintLayer* m_currentNormalFlowChild;
 };
 
 } // namespace blink
 
 #endif // DeprecatedPaintLayerStackingNodeIterator_h