From 814f3d01ef637921dfd65087aa59cd114aba9bbb Mon Sep 17 00:00:00 2001
From: Victor Berchet <victor@suumit.com>
Date: Sat, 24 Jan 2015 13:33:58 +0100
Subject: [PATCH] Doc(LightDom): add some inline doc

---
 .../compiler/shadow_dom_emulation/content_tag.js    | 13 +++++++------
 .../src/compiler/shadow_dom_emulation/light_dom.js  | 11 +++++++++++
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/modules/core/src/compiler/shadow_dom_emulation/content_tag.js b/modules/core/src/compiler/shadow_dom_emulation/content_tag.js
index 47fc62836a..c812f22e62 100644
--- a/modules/core/src/compiler/shadow_dom_emulation/content_tag.js
+++ b/modules/core/src/compiler/shadow_dom_emulation/content_tag.js
@@ -9,7 +9,7 @@ import {NgElement} from 'core/dom/element';
 var _scriptTemplate = DOM.createScriptTag('type', 'ng/content')
 
 class ContentStrategy {
-  nodes;
+  nodes: List<Node>;
   insert(nodes:List<Nodes>){}
 }
 
@@ -21,19 +21,21 @@ class ContentStrategy {
 class RenderedContent extends ContentStrategy {
   beginScript:Element;
   endScript:Element;
-  nodes:List<Node>;
 
-  constructor(el:Element) {
-    this._replaceContentElementWithScriptTags(el);
+  constructor(contentEl:Element) {
+    this._replaceContentElementWithScriptTags(contentEl);
     this.nodes = [];
   }
 
+  // Inserts the nodes in between the start and end scripts.
+  // Previous content is removed.
   insert(nodes:List<Node>) {
     this.nodes = nodes;
     DOM.insertAllBefore(this.endScript, nodes);
     this._removeNodesUntil(ListWrapper.isEmpty(nodes) ? this.endScript : nodes[0]);
   }
 
+  // Replaces the content tag with a pair of script tags
   _replaceContentElementWithScriptTags(contentEl:Element) {
     this.beginScript = DOM.clone(_scriptTemplate);
     this.endScript = DOM.clone(_scriptTemplate);
@@ -60,7 +62,6 @@ class RenderedContent extends ContentStrategy {
  */
 class IntermediateContent extends ContentStrategy {
   destinationLightDom:LightDom;
-  nodes:List<Node>;
 
   constructor(destinationLightDom:LightDom) {
     this.destinationLightDom = destinationLightDom;
@@ -95,4 +96,4 @@ export class Content {
   insert(nodes:List<Node>) {
     this._strategy.insert(nodes);
   }
-}
\ No newline at end of file
+}
diff --git a/modules/core/src/compiler/shadow_dom_emulation/light_dom.js b/modules/core/src/compiler/shadow_dom_emulation/light_dom.js
index 5f9582f8cf..19cfc9ffda 100644
--- a/modules/core/src/compiler/shadow_dom_emulation/light_dom.js
+++ b/modules/core/src/compiler/shadow_dom_emulation/light_dom.js
@@ -24,8 +24,11 @@ class _Root {
 // TODO: LightDom should implement SourceLightDom and DestinationLightDom
 // once interfaces are supported
 export class LightDom {
+  // The light DOM of the element is enclosed inside the lightDomView
   lightDomView:View;
+  // The shadow DOM
   shadowDomView:View;
+  // The nodes of the light DOM
   nodes:List<Node>;
   roots:List<_Root>;
 
@@ -47,6 +50,7 @@ export class LightDom {
     return this._collectAllContentTags(this.shadowDomView, []);
   }
 
+  // Collects the Content directives from the view and all its child views
   _collectAllContentTags(view: View, acc:List<Content>):List<Content> {
     var eis = view.elementInjectors;
     for (var i = 0; i < eis.length; ++i) {
@@ -66,6 +70,10 @@ export class LightDom {
     return acc;
   }
 
+  // Collects the nodes of the light DOM by merging:
+  // - nodes from enclosed ViewPorts,
+  // - nodes from enclosed content tags,
+  // - plain DOM nodes
   expandedDomNodes():List {
     var res = [];
 
@@ -90,6 +98,8 @@ export class LightDom {
     return res;
   }
 
+  // Returns a list of Roots for all the nodes of the light DOM.
+  // The Root object contains the DOM node and its corresponding injector (could be null).
   _roots() {
     if (isPresent(this.roots)) return this.roots;
 
@@ -101,6 +111,7 @@ export class LightDom {
   }
 }
 
+// Projects the light DOM into the shadow DOM
 function redistributeNodes(contents:List<Content>, nodes:List<Node>) {
   for (var i = 0; i < contents.length; ++i) {
     var content = contents[i];