feat(doc): Animation library documentation updates and fixes.

Closes dart-archive#760

Author: codelogic

lib/animate/module.dart

@@ -1,32 +1,46 @@
 /**
+ * Css animation and dom lifecycle management for Angular.
+ *
  * The [animate] library makes it easier to build animations that affect the
- * lifecycle of dom elements. The cononical example of this is animating the
- * removal of an element from the dom. In order to do this,
- * one must know about the duration of the animation, and immediatly perform
- * changes in the backing data model. The animation library uses computed css
- * styles to calculate the total duration of animation and handles the addition
- * and removal of elements for the dom for elements that are manipulated by
- * block level directives such as `ng-if`, `ng-repeat`, `ng-hide`, and more.
+ * lifecycle of dom elements. A useful example of this is animating the
+ * removal of an element from the dom. In order to do this ideally the
+ * operation should immediatly execute and manipulate the data model,
+ * and the framework should handle the actual remove of the dom element once
+ * the animation complets. This ensures that the logic and model of the
+ * application is seperated so that the state of the model can be reasoned
+ * about without having to wory about future modifications of the model.
+ * This library uses computed css styles to calculate the total duration
+ * of an animation and handles the addition, removal, and modification of dom
+ * elements for block level directives such as `ng-if`, `ng-repeat`,
+ * `ng-hide`, and more.
  *
  * To use, install the NgAnimateModule into your main module:
  *
- *    var module = new Module()
+ *     var module = new Module()
  *       ..install(new NgAnimateModule());
  *
- * Once this is installed, all block level dom manipulations will be routed
- * through the [CssAnimate] implementation instead of the default [NgAnimate]
- * class.
+ * Once the module has been installed, all block level dom manipulations will
+ * be routed through the [CssAnimate] class instead of the
+ * default [NgAnimate] implementation. This will, in turn,
+ * perform the tracking, manipulation, and computation for animations.
  *
- * For dom manipulations, this will add the `.ng-enter` class to a new dom
- * element, and then read the computed style. If there is a transition or
- * keyframe animation, the animation duration will be read,
+ * As an example of how this works, lets walk through what happens whan an
+ * element is added to the dom. The [CssAnimate] implementation will add the
+ * `.ng-enter` class to new dom elements when they are inserted into the dom
+ * by a directive and will read the computed style. If there is a
+ * transition or keyframe animation, that animation duration will be read,
  * and the animation will be performed. The `.ng-enter-active` class will be
- * added to set the target state for transition based animations. For
- * removing elements from the dom, a simliar pattern is followed. The
+ * added to the dom element to set the target state for transition based
+ * animations. When the animation is complete (determined by the
+ * precomputed duration) the `.ng-enter` and `.ng-enter-active` classes
+ * will be removed from the dom element.
+ *
+ * When removing elements from the dom, a simliar pattern is followed. The
  * `.ng-leave` class will be added to an element, the transition and / or
  * keyframe animation duration will be computed, and if it is non-zero the
- * animation will be run by adding the `.ng-leave-active` class,
- * and the element will be physically removed after the animation completes.
+ * animation will be run by adding the `.ng-leave-active` class. When
+ * the animation completes, the element will be physically removed from the
+ * dom.
  *
  * The same set of steps is run for each of the following types of dom
  * manipulation:
@@ -35,25 +49,25 @@
  * * `.ng-leave`
  * * `.ng-move`
  * * `.{cssclass}-add`
- * * `.{cssclasss}-remove`
+ * * `.{cssclass}-remove`
  *
  * When writing the css for animating a component you should avoid putting
- * css transitions on elements that might be animated, otherwise there may be
+ * css transitions on elements that might be animated or there may be
  * unintended pauses or side effects when an element is removed.
  *
  * Fade out example:
  *
  * HTML:
- *     <div class="goodby" ng-if="ctrl.visible">
- *       Goodby world!
+ *     <div class="goodbye" ng-if="ctrl.visible">
+ *       Goodbye world!
  *     </div>
  *
  * CSS:
- *     .goodby.ng-leave {
+ *     .goodbye.ng-leave {
  *       opacity: 1;
  *       transition: opacity 1s;
  *     }
- *     .goodby.ng-leave.ng-leave-active {
+ *     .goodbye.ng-leave.ng-leave-active {
  *       opacity: 0;
  *     }
  *