Document reflection

third_party/WebKit/Source/core/paint/PaintLayerReflectionInfo.h

Index: third_party/WebKit/Source/core/paint/PaintLayerReflectionInfo.h
diff --git a/third_party/WebKit/Source/core/paint/PaintLayerReflectionInfo.h b/third_party/WebKit/Source/core/paint/PaintLayerReflectionInfo.h
index 226fb3eba3e678b300168105f441b6603c418363..81dfd28a494e85ed70e1493a91860ae2e41ee797 100644
--- a/third_party/WebKit/Source/core/paint/PaintLayerReflectionInfo.h
+++ b/third_party/WebKit/Source/core/paint/PaintLayerReflectionInfo.h
@@ -55,6 +55,18 @@ 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);
@@ -75,10 +87,16 @@ 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;
 };