Add documentation on cc/Blink nodes, ids, and indices.

third_party/WebKit/Source/platform/graphics/compositing/PaintArtifactCompositor.cpp

Index: third_party/WebKit/Source/platform/graphics/compositing/PaintArtifactCompositor.cpp
diff --git a/third_party/WebKit/Source/platform/graphics/compositing/PaintArtifactCompositor.cpp b/third_party/WebKit/Source/platform/graphics/compositing/PaintArtifactCompositor.cpp
index 036586341f78c05f5737cfd7675d1a319dd5883c..2e230c62140fa077bdc7db675c3fd30b446511a5 100644
--- a/third_party/WebKit/Source/platform/graphics/compositing/PaintArtifactCompositor.cpp
+++ b/third_party/WebKit/Source/platform/graphics/compositing/PaintArtifactCompositor.cpp
@@ -603,6 +603,38 @@ class PropertyTreeManager {
   void setupRootEffectNode();
   void setupRootScrollNode();
 
+  // A brief discourse on cc property tree nodes, identifiers, and current and
+  // future design evolution envisioned:
+  //
+  // cc property trees identify nodes by their |id|, which implementation-wise
+  // is actually its index in the property tree's vector of its node type. More
+  // recent cc code now refers to these as 'node indices', or 'property tree
+  // indices'. |parent_id| is the same sort of 'node index' of that node's
+  // parent, whereas |owner_id| is the layer id of the layer owning that node.
+  //
+  // Note there are two other primary types of 'ids' referenced in cc property
+  // tree related logic: (1) ElementId, also known Blink-side as
+  // CompositorElementId, used by the animation system to allow tying an element
+  // to its respective layer, and (2) layer ids. There are other ancillary ids
+  // not relevant to any of the above, such as
+  // cc::TransformNode::sorting_context_id
+  // (a.k.a. blink::TransformPaintPropertyNode::renderingContextId()).
+  //
+  // There is a vision to move toward a world where cc property nodes have no
+  // association with layers and instead have a |stable_id|. The id could come
+  // from an ElementId in turn derived from the layout object responsible for
+  // creating the property node.
+  //
+  // We would also like to explore moving to use a single shared property tree
+  // representation across both cc and Blink. See
+  // platform/graphics/paint/README.md for more.
+  //
+  // With the above as background, we can now state more clearly a description
+  // of the below set of compositor id generation methods: they take Blink paint
+  // property tree nodes as input and produce a corresponding cc 'node id',
+  // a.k.a., 'node index', for use as we build out the corresponding cc property
+  // tree representation.
+
   int compositorIdForTransformNode(const TransformPaintPropertyNode*);
   int compositorIdForClipNode(const ClipPaintPropertyNode*);
   int switchToEffectNode(const EffectPaintPropertyNode& nextEffect);
@@ -640,6 +672,8 @@ class PropertyTreeManager {
 
   struct BlinkEffectAndCcIdPair {
     const EffectPaintPropertyNode* effect;
+    // The cc property tree effect node id, or 'node index', for the cc effect
+    // node corresponding to the above Blink effect paint property node.
     int id;
   };
   Vector<BlinkEffectAndCcIdPair> m_effectStack;
@@ -661,7 +695,7 @@ void PropertyTreeManager::setupRootTransformNode() {
   transformTree.SetTargetId(transformNode.id, kRealRootNodeId);
   transformTree.SetContentTargetId(transformNode.id, kRealRootNodeId);
 
-  // TODO(jaydasika): We shouldn't set ToScreeen and FromScreen of root
+  // TODO(jaydasika): We shouldn't set ToScreen and FromScreen of root
   // transform node here. They should be set while updating transform tree in
   // cc.
   float deviceScaleFactor = m_rootLayer->GetLayerTree()->device_scale_factor();