docs(directives): edits to directive docs

Author: naomiblack

lib/core/annotation_src.dart

@@ -236,7 +236,7 @@ bool _applyAuthorStylesDeprecationWarningPrinted = false;
 bool _resetStyleInheritanceDeprecationWarningPrinted = false;
 
 /**
- * Meta-data marker placed on a class which should act as a controller for the
+ * Annotation placed on a class which should act as a controller for the
  * component. Angular components are a light-weight version of web-components.
  * Angular components use shadow-DOM for rendering their templates.
  *
@@ -249,7 +249,8 @@ bool _resetStyleInheritanceDeprecationWarningPrinted = false;
  *
  * * `attach()` - Called on first [Scope.apply()].
  * * `detach()` - Called on when owning scope is destroyed.
- * * `onShadowRoot(ShadowRoot shadowRoot)` - Called when [ShadowRoot] is loaded.
+ * * `onShadowRoot(ShadowRoot shadowRoot)` - Called when
+ * [ShadowRoot](https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/dart-dom-html.ShadowRoot) is loaded.
  */
 class Component extends Directive {
   /**
@@ -362,7 +363,7 @@ class Component extends Directive {
 }
 
 /**
- * Meta-data marker placed on a class which should act as a directive.
+ * Annotation placed on a class which should act as a directive.
  *
  * Angular directives are instantiated using dependency injection, and can
  * ask for any injectable object in their constructor. Directives
@@ -402,7 +403,7 @@ class Decorator extends Directive {
 }
 
 /**
- * Meta-data marker placed on a class which should act as a controller for your
+ * Annotation placed on a class which should act as a controller for your
  * application.
  *
  * Controllers are essentially [Decorator]s with few key differences:

lib/directive/a_href.dart

@@ -1,14 +1,13 @@
 part of angular.directive;
 
 /**
- * Modifies the default behavior of the HTML `<a>` element to allow for data binding.
+ * Modifies the default behavior of the HTML `<a>` element to prevent navigation from the current page when the `href`
+ * attribute is empty. `Selector: a[href]`
  *
- * When an `href` tag is empty, or when used with `ng-click`, this directive intercepts and
- * modifies  the default behavior of the `<a>` element. This change permits the easy
- * creation of action links with the [OnClick] directive, without changing the location or causing
- * a page reload.
+ * This change permits the easy creation of action links with the [OnClick] directive, without changing the location
+ * or causing a page reload.
  *
-* Example:
+ * # Example
  *
  *     <a href="" ng-click="model.save()">Save</a>
  */

lib/directive/module.dart

@@ -7,7 +7,8 @@
  * and providing them as part of a custom library.
  *
  * Directives consist of a class specifying the behavior, and a directive annotation (such as a
- * [Decorator] or a [Component]) that describes when the behavior should be applied.
+ * [Decorator](#angular-core-annotation.Decorator) or a [Component](#angular-core-annotation.Component)) that
+  * describes when the behavior should be applied.
  *
  * For example:
  *

lib/directive/ng_base_css.dart

@@ -1,5 +1,13 @@
 part of angular.directive;
-
+/**
+ * Specifies a base CSS to use for components defined under the directive. `Selector:[ng-base-css]`
+ *
+ * The NgBaseCss directive is typically used at the top of an Angular application, so that everything in the
+ * application inherits the specified stylesheet.
+ *
+ * # Example
+ *     <div ng-base-css="my_application.css">
+ */
 @Decorator(selector: '[ng-base-css]')
 class NgBaseCss {
   List<String> _urls = const [];

lib/directive/ng_bind.dart

@@ -2,15 +2,15 @@ part of angular.directive;
 
 /**
  * Replaces the text content of the specified HTML element with the value of a given expression,
- * and updates the text content when the value of that expression changes.
+ * and updates the text content when the value of that expression changes. `Selector:[ng-bind]`
  *
  * Typically, you don't use ngBind directly, but instead you use the double
- * curly markup like `{{ expression }}` which is similar but less verbose.
+ * curly markup `{{ expression }}` which is similar but less verbose.
  *
- * It is preferrable to use `ng-bind` instead of `{{ expression }}` when a template
- * is momentarily displayed by the browser in its raw state before Angular
- * compiles it. Since `ng-bind` is an element attribute, it makes the bindings
- * invisible to the user while the page is loading.
+ * When a page loads in the browser, the template is briefly displayed in its raw state before Angular compiles it.
+ * For a large single-page app, this can result in `{{ }}` appearing while the page loads. You can prevent the template
+ * bindings from showing by using `ng-bind` instead of `{{ }}`. Since `ng-bind` is an element attribute, nothing is
+ * shown to the user.
  *
  * An alternative solution to this problem would be using the [ngCloak] directive.
  */

lib/directive/ng_bind_html.dart

@@ -1,18 +1,14 @@
 part of angular.directive;
 
 /**
- * Creates a binding that will innerHTML the result of evaluating the
- * `expression` bound to `ng-bind-html` into the current element in a secure
- * way.  This expression must evaluate to a string.  The innerHTML-ed content
- * will be sanitized using a default [NodeValidator] constructed as `new
- * dom.NodeValidatorBuilder.common()`.  In a future version, when Strict
- * Contextual Escaping support has been added to Angular.dart, this directive
- * will allow one to bypass the sanitization and innerHTML arbitrary trusted
- * HTML.
+ * Sanitizes an HTML string and invokes the browser's parser to insert the string into
+ * the containing element in the DOM. `Selector:[ng-bind-html]`
  *
- * Example:
+ * # Example
  *
- *     <div ng-bind-html="htmlVar"></div>
+ *     <div ng-bind-html="expression"></div>
+ *
+ * The expression must evaluate to a string. Content is sanitized using a default [NodeValidator].
  */
 @Decorator(
   selector: '[ng-bind-html]',
@@ -24,9 +20,10 @@ class NgBindHtml {
   NgBindHtml(this.element, dom.NodeValidator this.validator);
 
   /**
-   * Parsed expression from the `ng-bind-html` attribute.  The result of this
-   * expression is innerHTML'd according to the rules specified in this class'
-   * documentation.
+   * Parsed expression from the `ng-bind-html` attribute. 
+   *
+   * The result of this expression is inserted into the containing element in the DOM according to the
+   * rules specified in the documentation for the class.
    */
   void set value(value) => element.setInnerHtml(
       value == null ? '' : value.toString(), validator: validator);

lib/directive/ng_bind_template.dart

@@ -1,10 +1,13 @@
 part of angular.directive;
 
 /**
- * The [NgBindTemplate] specifies that the element text content should
- * be replaced with the interpolation of the template in the ngBindTemplate
- * attribute. Unlike ngBind, the ngBindTemplate can contain multiple {{ }}
- * expressions.
+ * Replaces the text content of an element with an interpolated template. `Selector:[ng-bind-template]`
+ *
+ * # Example
+ *
+ *     <div ng-bind-template="{{salutation}} {{name}}!">
+ *
+ * Unlike [ngBind], the `ng-bind-template` attribute can contain multiple `{{ }}` expressions.
  */
 @Decorator(
     selector: '[ng-bind-template]',

lib/directive/ng_class.dart

@@ -11,8 +11,8 @@ part of angular.directive;
  *  * Array syntax: If the expression is an array, CSS classes are additively applied to the
  *    element.
  *  * Map syntax: If the expression is a map of 'key':value pairs, then the truthiness of the
- *    value is used to determine which CSS classes are applied. (Here,
- *    the keys correspond to the CSS classes to be applied.)
+ *    value is used to determine which CSS classes are applied. (Here, the keys correspond to the
+ *    CSS classes to be applied.)
  *
  * The directive won't add duplicate classes if a particular class was already set. When the
  * expression changes, CSS classes are updated to reflect the change.
@@ -82,6 +82,8 @@ class NgClass extends _NgClassBase {
 }
 
 /**
+ * Dynamically style only odd rows in a list via data.
+ *
  * The `ngClassOdd` and `ngClassEven` directives work exactly as
  * {@link ng.directive:ngClass ngClass}, except it works in
  * conjunction with `ngRepeat` and takes affect only on odd (even) rows.