Add documentation to 2 DeprecatedPaintLayer objects

Source/core/paint/DeprecatedPaintLayerStackingNode.h

 /*
  * Copyright (C) 2003, 2009, 2012 Apple Inc. All rights reserved.
  * Copyright (C) 2013 Intel Corporation. All rights reserved.
  *
  * Portions are Copyright (C) 1998 Netscape Communications Corporation.
  *
  * Other contributors:
  *   Robert O'Callahan <roc+@cs.cmu.edu>
  *   David Baron <dbaron@fas.harvard.edu>
  *   Christian Biesinger <cbiesinger@web.de>
@@ skipping 40 matching lines @@
 #include "wtf/OwnPtr.h"
 #include "wtf/Vector.h"
 
 namespace blink {
 
 class DeprecatedPaintLayer;
 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);
 public:
     explicit DeprecatedPaintLayerStackingNode(LayoutBoxModelObject&);
     ~DeprecatedPaintLayerStackingNode();
 
     int zIndex() const { return layoutObject().style()->zIndex(); }
 
     bool isStackingContext() const { return layoutObject().style()->isStackingContext(); }
@@ skipping 122 matching lines @@
 
 private:
     DeprecatedPaintLayerStackingNode* m_stackingNode;
     bool m_previousMutationAllowedState;
 };
 #endif
 
 } // namespace blink
 
 #endif // DeprecatedPaintLayerStackingNode_h