Document reflection

third_party/WebKit/Source/core/paint/PaintLayerReflectionInfo.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 37 matching lines @@
 #include "core/layout/LayoutBoxModelObject.h"
 #include "core/paint/PaintLayerPainter.h"
 #include "wtf/Allocator.h"
 #include "wtf/Noncopyable.h"
 
 namespace blink {
 
 class PaintLayer;
 class LayoutReplica;
 
+// PaintLayerReflectionInfo is the main object used for reflections.
+// https://www.webkit.org/blog/182/css-reflections/
+//
+// All reflection operations are done through this object, which delegates to
+// LayoutReplica and ReflectionPainter.
+//
+// Painting Reflections is handled by painting the same PaintLayer again with
+// some special paint flags (the most important being
+// PaintLayerPaintingReflection). See PaintLayerReflectionInfo::paint() and
+// ReplicaPainter for the entry point into the reflection painting code.
+//
+// See LayoutReplica for the peculiar tree structure generated by this design.
 class PaintLayerReflectionInfo {
     WTF_MAKE_FAST_ALLOCATED(PaintLayerReflectionInfo);
     WTF_MAKE_NONCOPYABLE(PaintLayerReflectionInfo);
 public:
     explicit PaintLayerReflectionInfo(LayoutBox&);
     void destroy();
 
     LayoutReplica* reflection() const { return m_reflection; }
     PaintLayer* reflectionLayer() const;
 
     bool isPaintingInsideReflection() const { return m_isPaintingInsideReflection; }
 
     void updateAfterStyleChange(const ComputedStyle* oldStyle);
 
     void paint(GraphicsContext*, const PaintLayerPaintingInfo&, PaintLayerFlags);
 
 private:
     LayoutBox& box() { return *m_box; }
     const LayoutBox& box() const { return *m_box; }
 
+    // The reflected box, ie the box with -webkit-box-reflect.
     LayoutBox* m_box;
+
+    // The reflection object.
+    // This LayoutObject is owned by PaintLayerReflectinInfo.
     LayoutReplica* m_reflection;
 
-    // A state bit tracking if we are painting inside a replica.
+    // A state bit tracking if we are painting inside this replica.
+    // This is done to avoid infinite recursion during painting while also
+    // enabling nested reflection.
     unsigned m_isPaintingInsideReflection : 1;
 };
 
 } // namespace blink
 
 #endif // PaintLayerReflectinInfo_h