docs($compile): fix typos and incorrect example

src/ng/compile.js

@@ -205,7 +205,7 @@
  *
  * This example show how you might use `$doCheck` to trigger changes in your component's inputs even if the
  * actual identity of the component doesn't change. (Be aware that cloning and deep equality checks on large
- * arrays or objects can have a negative impact on your application performance)
+ * arrays or objects can have a negative impact on your application performance.)
  *
  * <example name="doCheckArrayExample" module="do-check-module">
  * <file name="index.html">
@@ -528,7 +528,7 @@
  * would result in the whole app "stalling" until all templates are loaded asynchronously - even in the
  * case when only one deeply nested directive has `templateUrl`.
  *
- * Template loading is asynchronous even if the template has been preloaded into the {@link $templateCache}
+ * Template loading is asynchronous even if the template has been preloaded into the {@link $templateCache}.
  *
  * You can specify `templateUrl` as a string representing the URL or as a function which takes two
  * arguments `tElement` and `tAttrs` (described in the `compile` function api below) and returns
@@ -589,7 +589,7 @@
  * own templates or compile functions. Compiling these directives results in an infinite loop and
  * stack overflow errors.
  *
- * This can be avoided by manually using $compile in the postLink function to imperatively compile
+ * This can be avoided by manually using `$compile` in the postLink function to imperatively compile
  * a directive's template instead of relying on automatic template compilation via `template` or
  * `templateUrl` declaration or manual compilation inside the compile function.
  * </div>
@@ -693,17 +693,17 @@
  *
  * * `true` - transclude the content (i.e. the child nodes) of the directive's element.
  * * `'element'` - transclude the whole of the directive's element including any directives on this
- * element that defined at a lower priority than this directive. When used, the `template`
+ * element that are defined at a lower priority than this directive. When used, the `template`
  * property is ignored.
  * * **`{...}` (an object hash):** - map elements of the content onto transclusion "slots" in the template.
  *
- * **Mult-slot transclusion** is declared by providing an object for the `transclude` property.
+ * **Multi-slot transclusion** is declared by providing an object for the `transclude` property.
  *
  * This object is a map where the keys are the name of the slot to fill and the value is an element selector
  * used to match the HTML to the slot. The element selector should be in normalized form (e.g. `myElement`)
  * and will match the standard element variants (e.g. `my-element`, `my:element`, `data-my-element`, etc).
  *
- * For further information check out the guide on {@link guide/directive#matching-directives Matching Directives}
+ * For further information check out the guide on {@link guide/directive#matching-directives Matching Directives}.
  *
  * If the element selector is prefixed with a `?` then that slot is optional.
  *
@@ -728,7 +728,7 @@
  * </div>
  *
  * If you want to manually control the insertion and removal of the transcluded content in your directive
- * then you must use this transclude function. When you call a transclude function it returns a a jqLite/JQuery
+ * then you must use this transclude function. When you call a transclude function it returns a jqLite/JQuery
  * object that contains the compiled DOM, which is linked to the correct transclusion scope.
  *
  * When you call a transclusion function you can pass in a **clone attach function**. This function accepts
@@ -813,8 +813,8 @@
  * The {@link ng.$compile.directive.Attributes Attributes} object - passed as a parameter in the
  * `link()` or `compile()` functions. It has a variety of uses.
  *
- * * *Accessing normalized attribute names:* Directives like 'ngBind' can be expressed in many ways:
- * 'ng:bind', `data-ng-bind`, or 'x-ng-bind'. The attributes object allows for normalized access
+ * * *Accessing normalized attribute names:* Directives like `ngBind` can be expressed in many ways:
+ * `ng:bind`, `data-ng-bind`, or `x-ng-bind`. The attributes object allows for normalized access
  * to the attributes.
  *
  * * *Directive inter-communication:* All directives share the same instance of the attributes
@@ -855,25 +855,24 @@
  <file name="index.html">
  <script>
  angular.module('compileExample', [], function($compileProvider) {
- // configure new 'compile' directive by passing a directive
- // factory function. The factory function injects the '$compile'
+ // Configure new 'compile' directive by passing a directive
+ // factory function. The factory function injects '$compile'.
  $compileProvider.directive('compile', function($compile) {
- // directive factory creates a link function
+ // The directive factory creates a link function.
  return function(scope, element, attrs) {
  scope.$watch(
  function(scope) {
-  // watch the 'compile' expression for changes
+ // Watch the 'compile' expression for changes.
  return scope.$eval(attrs.compile);
  },
  function(value) {
- // when the 'compile' expression changes
- // assign it into the current DOM
+ // When the 'compile' expression changes
+ // assign it into the current DOM.
  element.html(value);
 
- // compile the new DOM and link it to the current
- // scope.
- // NOTE: we only compile .childNodes so that
- // we don't get into infinite loop compiling ourselves
+ // Compile the new DOM and link it to the current scope.
+ // NOTE: we only compile '.childNodes' so that we
+ // don't get into an infinite loop compiling ourselves.
  $compile(element.contents())(scope);
  }
  );
@@ -946,35 +945,37 @@
  * }
  * ```
  * * `futureParentElement` - defines the parent to which the `cloneAttachFn` will add
- * the cloned elements; only needed for transcludes that are allowed to contain non html
- * elements (e.g. SVG elements). See also the directive.controller property.
+ * the cloned elements; only needed for transcludes that are allowed to contain non HTML
+ * elements (e.g. SVG elements). See also the `directive.controller` property.
  *
  * Calling the linking function returns the element of the template. It is either the original
  * element passed in, or the clone of the element if the `cloneAttachFn` is provided.
  *
- * After linking the view is not updated until after a call to $digest which typically is done by
+ * After linking the view is not updated until after a call to `$digest`, which typically is done by
  * AngularJS automatically.
  *
  * If you need access to the bound view, there are two ways to do it:
  *
  * - If you are not asking the linking function to clone the template, create the DOM element(s)
  * before you send them to the compiler and keep this reference around.
  * ```js
- * var element = $compile('<p>{{total}}</p>')(scope);
+ * var element = angular.element('<p>{{total}}</p>');
+ * $compile(element)(scope);
  * ```
  *
  * - if on the other hand, you need the element to be cloned, the view reference from the original
  * example would not point to the clone, but rather to the original template that was cloned. In
- * this case, you can access the clone via the cloneAttachFn:
+ * this case, you can access the clone either via the `cloneAttachFn` or the value returned by the
+ * linking function:
  * ```js
- * var templateElement = angular.element('<p>{{total}}</p>'),
- * scope = ....;
- *
+ * var templateElement = angular.element('<p>{{total}}</p>');
  * var clonedElement = $compile(templateElement)(scope, function(clonedElement, scope) {
- * //attach the clone to DOM document at the right place
+ * // Attach the clone to DOM document at the right place.
  * });
  *
- * //now we have reference to the cloned DOM via `clonedElement`
+ * // Now we have reference to the cloned DOM via `clonedElement`.
+ * // NOTE: The `clonedElement` returned by the linking function is the same as the
+ * // `clonedElement` passed to `cloneAttachFn`.
  * ```
  *
  *
@@ -1500,9 +1501,9 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
  * @description
  * Register a new directive with the compiler.
  *
- * @param {string|Object} name Name of the directive in camel-case (i.e. <code>ngBind</code> which
- * will match as <code>ng-bind</code>), or an object map of directives where the keys are the
- * names and the values are the factories.
+ * @param {string|Object} name Name of the directive in camel-case (i.e. `ngBind` which will match
+ * as `ng-bind`), or an object map of directives where the keys are the names and the values
+ * are the factories.
  * @param {Function|Array} directiveFactory An injectable directive factory function. See the
  * {@link guide/directive directive guide} and the {@link $compile compile API} for more info.
  * @returns {ng.$compileProvider} Self for chaining.