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
+// 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
+// objects of this class to be a node in this tree but there are potential
+// issues with stale pointers so we rely on DeprecatedPaintLayer's tree
+// structure.
+//
+// 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.
+//
+// To implement any z-order list iterations, use
+// DeprecatedPaintLayerStackingNodeIterator and
+// DeprecatedPaintLayerStackingNodeReverseIterator.
+//
+// This class is NOT DEPRECATED, DeprecatedPaintLayer is and we match its
+// naming.
 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