docs(directive, module): add various missing docs and fix existing docs

5 files changed, 56 insertions, 26 deletions

diff --git a/docs/content/api/angular.module.ng.$compileProvider.directive.ngdoc b/docs/content/api/angular.module.ng.$compileProvider.directive.ngdoc
index 356414fb..b7acf680 100644
--- a/docs/content/api/angular.module.ng.$compileProvider.directive.ngdoc
+++ b/docs/content/api/angular.module.ng.$compileProvider.directive.ngdoc
@@ -241,7 +241,6 @@ The full skeleton of the directive is shown here:
       transclude: false,
       restrict: 'A',
       scope: false,
-      local: {},
       compile: function compile(tElement, tAttrs, transclude) {
         return {
           pre: function preLink(scope, iElement, iAttrs, controller) { ... },
@@ -319,35 +318,35 @@ compiler}. The attributes are:
     * `{}` (object hash) - then a new 'isolate' scope is created. The 'isolate' scope differs from
       normal scope that it does not prototypically inherit from the parent scope. This is useful
       when creating reusable components, which should not accidentally read or modify data in
-      parent scope. <br/> 
+      parent scope. <br/>
       The 'isolate' scope takes an object hash which defines a set of local scope properties
       derived from the parent scope. These local properties are useful for aliasing values for
       templates. Locals definition is a hash of normalized element attribute name to their
       corresponding binding strategy. Valid binding strategies are:
 
       * `attribute` - one time read of element attribute value and save it to widget scope. <br/>
-        Given `<widget my-attr='abc'>` and widget definition of `locals: {myAttr:'attribute'}`,
+        Given `<widget my-attr='abc'>` and widget definition of `scope: {myAttr:'attribute'}`,
         then widget scope property `myAttr` will be `"abc"`.
 
       * `evaluate` - one time evaluation of expression stored in the attribute. <br/> Given
-        `<widget my-attr='name'>` and widget definition of `locals: {myAttr:'evaluate'}`, and
+        `<widget my-attr='name'>` and widget definition of `scope: {myAttr:'evaluate'}`, and
         parent scope `{name:'angular'}` then widget scope property `myAttr` will be `"angular"`.
 
       * `bind` - Set up one way binding from the element attribute to the widget scope. <br/>
-        Given `<widget my-attr='{{name}}'>` and widget definition of `locals: {myAttr:'bind'}`,
+        Given `<widget my-attr='{{name}}'>` and widget definition of `scope: {myAttr:'bind'}`,
         and parent scope `{name:'angular'}` then widget scope property `myAttr` will be
         `"angular"`, but any changes in the parent scope will be reflected in the widget scope.
 
       * `accessor` - Set up getter/setter function for the expression in the widget element
         attribute to the widget scope. <br/> Given `<widget my-attr='name'>` and widget definition
-        of `locals: {myAttr:'prop'}`, and parent scope `{name:'angular'}` then widget scope
+        of `scope: {myAttr:'prop'}`, and parent scope `{name:'angular'}` then widget scope
         property `myAttr` will be a function such that `myAttr()` will return `"angular"` and
         `myAttr('new value')` will update the parent scope `name` property. This is useful for
         treating the element as a data-model for reading/writing.
 
-      * `expression` - Treat element attribute as an expression to be executed in form of an event.
+      * `expression` - Treat element attribute as an expression to be executed on the parent scope.
         <br/>
-        Given `<widget my-attr='doSomething()'>` and widget definition of `locals:
+        Given `<widget my-attr='doSomething()'>` and widget definition of `scope:
         {myAttr:'expression'}`, and parent scope `{doSomething:function() {}}` then calling the
         widget scope function `myAttr` will execute the expression against the parent scope.
 
@@ -371,7 +370,7 @@ compiler}. The attributes are:
 
 
   * `inject` (object hash) -  Specifies a way to inject bindings into a controller. Injection
-    definition is a hash of normalized element attribute name to their corresponding binding
+    definition is a hash of normalized element attribute names to their corresponding binding
     strategy. Valid binding strategies are:
 
     * `attribute` - inject attribute value. <br/>
@@ -421,10 +420,10 @@ compiler}. The attributes are:
     transclusion function which is pre-bound to the correct scope. In a typical setup the widget
     creates an `isolate` scope, but the transclusion is not a child, but a sibling of the `isolate`
     scope. This makes it possible for the widget to have private state, and the transclusion to
-    be bound to the pre-`isolate` scope.
+    be bound to the parent (pre-`isolate`) scope.
 
     * `true` - transclude the content of the directive.
-    * `element` - transclude the whole element including any directives defined at lower priority.
+    * `'element'` - transclude the whole element including any directives defined at lower priority.
 
 
   * `compile`: This is the compile function described in the section below.
@@ -569,11 +568,11 @@ This will not render properly, unless we do some scope magic.
 The first issue we have to solve is that the dialog box template expect `title` to be defined, but
 the place of instantiation would like to bind to `username`. Furthermore the buttons expect `onOk`
 as well as `onCancel` functions to be present in the scope. This limits the usefulness of the
-widget. To solve the mapping issue we use the `locals` to create local variables which the
-template expects as follows
+widget. To solve the mapping issue we use the `locals` to create local variables which the template
+expects as follows:
 
 <pre>
-  locals: {
+  scope: {
     title: 'bind',   // set up title to accept data-binding
     onOk: 'exp',     // create a delegate onOk function
     onCancel: 'exp', // create a delegate onCancel function
diff --git a/docs/content/guide/module.ngdoc b/docs/content/guide/module.ngdoc
index 12ec8917..e3b3362f 100644
--- a/docs/content/guide/module.ngdoc
+++ b/docs/content/guide/module.ngdoc
@@ -19,7 +19,7 @@ approach:
 
 # The Basics
 
-Ok i am in a hurry how do i get a Hello World module working?
+Ok, I'm in a hurry how do i get a Hello World module working?
 
 Important things to notice:
 
@@ -116,7 +116,7 @@ The above is only a suggestion, so feel free to tailor it to your needs.
 
 # Module Loading & Dependencies
 
-A module is a collection of configuration and run block which get applied to the application
+A module is a collection of configuration and run blocks which get applied to the application
 during the bootstrap process. In its simplest form the module consist of collection of two kinds
 of blocks:
 
@@ -173,8 +173,8 @@ to it are constant definitions, which are placed at the beginning of all configu
 
 Run blocks are the closest thing in Angular to the main method. A run block is the code which
 needs to run to kickstart the application. It is executed after all of the service have been
-configured and the injector has been created. Run blocks typically contain code which is hard 
-to unit-test, and for this reason should be declared in isolated modules, so that they can be 
+configured and the injector has been created. Run blocks typically contain code which is hard
+to unit-test, and for this reason should be declared in isolated modules, so that they can be
 ignored in the unit-tests.
 
 ## Dependencies
@@ -223,19 +223,19 @@ In all of these examples we are going to assume this module definition:
 Let's write some tests:
 <pre>
 describe('myApp', function() {
-  // load the application relevant modules then load a special 
-  // test module which overrides the $window with mock version, 
-  // so that calling window.alert() will not block the test 
+  // load the application relevant modules then load a special
+  // test module which overrides the $window with mock version,
+  // so that calling window.alert() will not block the test
   // runner with a real alert box. This is an example of overriding
   // configuration information in tests.
   beforeEach(module('greetMod', function($provide) {
-    $provide.value('$window', { 
-      alert: jasmine.createSpy('alert') 
+    $provide.value('$window', {
+      alert: jasmine.createSpy('alert')
     });
   });
 
   // The inject() will create the injector and inject the greet and
-  // $window into the tests. The test need not concern itself with 
+  // $window into the tests. The test need not concern itself with
   // wiring of the application, only with testing it.
   it('should alert on $window', inject(function(greet, $window) {
     greet('World');
diff --git a/src/directives.js b/src/directives.js
index 1fc7f1b5..91241a16 100644
--- a/src/directives.js
+++ b/src/directives.js
@@ -196,6 +196,22 @@ var ngBindDirective = ngDirective(function(scope, element, attr) {
   });
 });
 
+
+/**
+ * @ngdoc directive
+ * @name angular.module.ng.$compileProvider.directive.ng:bind-html-unsafe
+ *
+ * @description
+ * Creates a binding that will innerHTML the result of evaluating the `expression` into the current
+ * element. *The innerHTML-ed content will not be sanitized!* You should use this directive only if
+ * {@link angular.module.ng.$compileProvider.directive.ng:bind-html ng:bind-html} directive is too
+ * restrictive and when you absolutely trust the source of the content you are binding to.
+ *
+ * See {@link angular.module.ng.$sanitize $sanitize} docs for examples.
+ *
+ * @element ANY
+ * @param {expression} expression {@link guide/dev_guide.expressions Expression} to evaluate.
+ */
 var ngBindHtmlUnsafeDirective = ngDirective(function(scope, element, attr) {
   element.addClass('ng-binding').data('$binding', attr.ngBindHtmlUnsafe);
   scope.$watch(attr.ngBindHtmlUnsafe, function(value) {
@@ -203,6 +219,21 @@ var ngBindHtmlUnsafeDirective = ngDirective(function(scope, element, attr) {
   });
 });
 
+
+/**
+ * @ngdoc directive
+ * @name angular.module.ng.$compileProvider.directive.ng:bind-html
+ *
+ * @description
+ * Creates a binding that will sanitize the result of evaluating the `expression` with the
+ * {@link angular.module.ng.$sanitize $sanitize} service and innerHTML the result into the current
+ * element.
+ *
+ * See {@link angular.module.ng.$sanitize $sanitize} docs for examples.
+ *
+ * @element ANY
+ * @param {expression} expression {@link guide/dev_guide.expressions Expression} to evaluate.
+ */
 var ngBindHtmlDirective = ['$sanitize', function($sanitize) {
   return function(scope, element, attr) {
     element.addClass('ng-binding').data('$binding', attr.ngBindHtml);
diff --git a/src/service/sanitize.js b/src/service/sanitize.js
index 1e201691..1446487c 100644
--- a/src/service/sanitize.js
+++ b/src/service/sanitize.js
@@ -63,7 +63,7 @@
              </tr>
              <tr id="escaped-html">
                <td>no filter</td>
-               <td><pre>&lt;div ng:bind-="snippet"&gt;<br/>&lt;/div&gt;</pre></td>
+               <td><pre>&lt;div ng:bind="snippet"&gt;<br/>&lt;/div&gt;</pre></td>
                <td><div ng:bind="snippet"></div></td>
              </tr>
              <tr id="html-unsafe-filter">
diff --git a/src/widgets.js b/src/widgets.js
index d3b4083f..235fbc2b 100644
--- a/src/widgets.js
+++ b/src/widgets.js
@@ -805,7 +805,7 @@ var ngPluralizeDirective = ['$locale', '$interpolate', function($locale, $interp
     restrict: 'EA',
     link: function(scope, element, attr) {
       var numberExp = attr.count,
-          whenExp = element.attr(attr.$attr.when), // this is becaues we have {{}} in attrs
+          whenExp = element.attr(attr.$attr.when), // this is because we have {{}} in attrs
           offset = attr.offset || 0,
           whens = scope.$eval(whenExp),
           whensExpFns = {};