Add documentation to 2 DeprecatedPaintLayer objects

Source/core/paint/DeprecatedPaintLayer.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 77 matching lines @@
     TemporaryChange<CompositingQueryMode> m_disabler;
 };
 
 // DeprecatedPaintLayer is an old object that handles lots of unrelated operations.
 // We want it to die at some point and be replaced by more focused objects. Removing
 // a lot of unneeded complexity.
 // Complex painting operations (opacity, clipping, filters, reflections, ...),
 // hardware acceleration (through DeprecatedPaintLayerCompositor),
 // scrolling (through DeprecatedPaintLayerScrollableArea)
 // along with some optimizations are all handled by DeprecatedPaintLayer.
+//
+// The class is DEPRECATED, which means that we would like to remove it. The
+// reason for removal is that it has been a dumping ground for features for too
+// long and is the wrong level of abstraction, bearing no correspondence to any
+// CSS concept. Its associated objects and some of its feature need to be
+// migrated to LayoutObject (or the appropriate sub-class).
 class CORE_EXPORT DeprecatedPaintLayer {
     WTF_MAKE_NONCOPYABLE(DeprecatedPaintLayer);
 public:
     DeprecatedPaintLayer(LayoutBoxModelObject*, DeprecatedPaintLayerType);
     ~DeprecatedPaintLayer();
 
     String debugName() const;
 
     LayoutBoxModelObject* layoutObject() const { return m_layoutObject; }
     LayoutBox* layoutBox() const { return m_layoutObject && m_layoutObject->isBox() ? toLayoutBox(m_layoutObject) : 0; }
@@ skipping 632 matching lines @@
 
 } // namespace blink
 
 #ifndef NDEBUG
 // Outside the WebCore namespace for ease of invocation from gdb.
 void showLayerTree(const blink::DeprecatedPaintLayer*);
 void showLayerTree(const blink::LayoutObject*);
 #endif
 
 #endif // Layer_h