Document reflection

third_party/WebKit/Source/core/layout/LayoutReplica.h

Index: third_party/WebKit/Source/core/layout/LayoutReplica.h
diff --git a/third_party/WebKit/Source/core/layout/LayoutReplica.h b/third_party/WebKit/Source/core/layout/LayoutReplica.h
index 6bf658d2f7e8ab51ac8a633ea605c91ec3aca04d..5efb741d2d0d952531c6ecbdccbdf9b7ae3abaa6 100644
--- a/third_party/WebKit/Source/core/layout/LayoutReplica.h
+++ b/third_party/WebKit/Source/core/layout/LayoutReplica.h
@@ -33,6 +33,30 @@
 
 namespace blink {
 
+// LayoutReplica is a synthetic object used to represent reflections.
+// https://www.webkit.org/blog/182/css-reflections/
+//
+// The object is part of the layout tree, however it is not fully inserted into
+// it: LayoutReplica::parent() will return the right information but the
+// parent's children() don't know about the LayoutReplica.
+// Note that its PaintLayer is fully inserted into the PaintLayer tree, which
+// requires some special casing in the painting code (e.g. in
+// PaintLayerStackingNode).
+//
+// LayoutReplica's parent() is the object with the -webkit-box-reflect.
+// LayoutReplica inherits its style from its parent() but also have an extra
+// 'transform' to paint the reflection correctly. This is done by
+// PaintLayerReflectionInfo.
+//
+// The object is created and managed by PaintLayerReflectionInfo. Also all of
+// its operations happen through PaintLayerReflectionInfo (e.g. layout, style
+// updates, ...).
+//
+// This class is a big hack. The original intent for it is unclear but has to do
+// with implementing the correct painting of reflection. It may be to apply a
+// 'transform' and offset during painting.
+// TODO(jchaffraix): This description is not great but I don't know why this

[mstensho (USE GERRIT), 2015/10/13 16:17:45]

I think this is just great. Nothing left TODO. :)

[Julien - ping for review, 2015/10/13 21:36:43]

Not going to argue with you :)

I am not happy that I couldn't find the exact reason for the class though and it
may be that there is none.

+// class exists and probably no one does.
 class LayoutReplica final : public LayoutBox {
 public:
     static LayoutReplica* createAnonymous(Document*);