@@ -79,55 +79,63 @@ Template.prototype = {
7979 * @function
8080 *
8181 * @description
82- * Compiles a piece of HTML string or DOM into a view and produces a linking function, which can
83- * then be used to link {@link angular.scope scope} and the template together. The compilation
84- * process walks the DOM tree and tries to match DOM elements to { @link angular.markup markup},
85- * { @link angular.attrMarkup attrMarkup}, { @link angular.widget widgets}, and
86- * {@link angular.directive directives}. For each match it executes coresponding markup, \
87- * attrMarkup, widget or directive template function and collects the instance functions into a
88- * single linking function which is then returned. The linking function can then be used
89- * many-times-over on clones of compiled DOM structure, (For example when compiling
90- * { @link angular.widget.@ng:repeat repeater} the resulting linking function is called once for
91- * each item in the collection. The `ng:repeat` does this by cloning the template DOM once for
92- * each item in collection and then calling the linking function to link the cloned template
93- * with the a new scope for each item in the collection.)
82+ * Compiles a piece of HTML string or DOM into a template and produces a template function, which
83+ * can then be used to link {@link angular.scope scope} and the template together.
84+ *
85+ * The compilation is a process of walking the DOM tree and trying to match DOM elements to
86+ * {@link angular.markup markup}, { @link angular.attrMarkup attrMarkup},
87+ * { @link angular. widget widgets}, and { @link angular.directive directives}. For each match it
88+ * executes coresponding markup, attrMarkup, widget or directive template function and collects the
89+ * instance functions into a single template function which is then returned.
90+ *
91+ * The template function can then be used once to produce the view or as it is the case with
92+ * { @link angular.widget.@ng:repeat repeater} many-times, in which case each call results in a view
93+ * that is a DOM clone of the original template.
9494 *
9595 <pre>
96- var mvc1 = angular.compile(window.document)();
97- mvc1.view; // compiled view elment
98- mvc1.scope; // scope bound to the element
96+ //copile the entire window.document and give me the scope bound to this template.
97+ var rootSscope = angular.compile(window.document)();
98+
99+ //compile a piece of html
100+ var rootScope2 = angular.compile(''<div ng:click="clicked = true">click me</div>')();
99101
100- var mvc2 = angular.compile('<div ng:click="clicked = true">click me</div>')();
102+ //compile a piece of html and retain reference to both the dom and scope
103+ var template = angular.element('<div ng:click="clicked = true">click me</div>'),
104+ scoope = angular.compile(view)();
105+ //at this point template was transformed into a view
101106 </pre>
102107 *
108+ *
103109 * @param {string|DOMElement } element Element or HTML to compile into a template function.
104- * @returns {function([scope][, cloneAttachFn]) } a template function which is used to bind element
105- * and scope. Where:
110+ * @returns {function([scope][, cloneAttachFn]) } a template function which is used to bind template
111+ * (a DOM element/tree) to a scope. Where:
106112 *
107- * * `scope` - {@link angular.scope scope} A scope to bind to. If none specified, then a new
113+ * * `scope` - A {@link angular.scope scope} to bind to. If none specified, then a new
108114 * root scope is created.
109115 * * `cloneAttachFn` - If `cloneAttachFn` is provided, then the link function will clone the
110116 * `template` and call the `cloneAttachFn` function allowing the caller to attach the
111117 * cloned elements to the DOM document at the approriate place. The `cloneAttachFn` is
112- * called as: <br/> `cloneAttachFn(clonedElement, scope)`:
118+ * called as: <br/> `cloneAttachFn(clonedElement, scope)` where :
113119 *
114120 * * `clonedElement` - is a clone of the original `element` passed into the compiler.
115121 * * `scope` - is the current scope with which the linking function is working with.
116122 *
117123 * Calling the template function returns the scope to which the element is bound to. It is either
118- * a new root scope or scope passed into the template function.
124+ * the same scope as the one passed into the template function, or if none were provided it's the
125+ * newly create scope.
119126 *
120- * If you need access to the compiled view, there are two ways to do it:
127+ * If you need access to the bound view, there are two ways to do it:
121128 *
122- * - either create the DOM element(s) before you send them to the compiler and keep this reference
123- * around. This works if you don't need the element to be cloned by the link function .
129+ * - If you are not asking the linking function to clone the template, create the DOM element(s)
130+ * before you send them to the compiler and keep this reference around .
124131 * <pre>
125132 * var view = angular.element('<p>{{total}}</p>'),
126133 * scope = angular.compile(view)();
127134 * </pre>
135+ *
128136 * - if on the other hand, you need the element to be cloned, the view reference from the original
129- * example would not point to the clone, but rather to the dom that is cloned. In this case,
130- * you can access the clone via the cloneAttachFn:
137+ * example would not point to the clone, but rather to the original template that was cloned. In
138+ * this case, you can access the clone via the cloneAttachFn:
131139 * <pre>
132140 * var original = angular.element('<p>{{total}}</p>'),
133141 * scope = someParentScope.$new(),
0 commit comments