doc(NodeAttrs): rework class comments, make namings consistent

Author: vicb

lib/core_dom/directive.dart

@@ -7,9 +7,12 @@ typedef void _AttributeChanged(String newValue);
 typedef void Mustache(bool hasObservers);
 
 /**
- * NodeAttrs is a facade for element attributes. The facade is responsible
- * for normalizing attribute names as well as allowing access to the
- * value of the directive.
+ * NodeAttrs is a facade for element attributes.
+ *
+ * This facade allows reading and writing the attribute values as well as
+ * adding observers triggered when:
+ * - The value of an attribute changes,
+ * - An element becomes observed.
  */
 class NodeAttrs {
   final dom.Element element;
@@ -30,15 +33,20 @@ class NodeAttrs {
     } else {
       element.attributes[attrName] = value;
     }
+
     if (_observers != null && _observers.containsKey(attrName)) {
       _observers[attrName].forEach((notifyFn) => notifyFn(value));
     }
   }
 
   /**
-   * Observe changes to the attribute by invoking the [notifyFn] function. On
-   * registration the [notifyFn] function gets invoked synchronize with the
-   * current value.
+   * Observes changes to the attribute by invoking the [notifyFn]
+   * function. On registration the [notifyFn] function gets invoked in order to
+   * synchronize with the current value.
+   *
+   * When an observed is registered on an attributes any existing
+   * [_observerListeners] will be called with the first parameter set to
+   * [:true:]
    */
   observe(String attrName, notifyFn(String value)) {
     if (_observers == null) _observers = <String, List<_AttributeChanged>>{};
@@ -61,14 +69,19 @@ class NodeAttrs {
 
   Iterable<String> get keys => element.attributes.keys;
 
+  /**
+   * Registers a listener to be called when the attribute [attrName] becomes
+   * observed. On registration [notifyFn] function gets invoked with [:false:]
+   * as the first argument.
+   */
   void listenObserverChanges(String attrName, Mustache notifyFn) {
     _mustacheAttrs[attrName] = new _MustacheAttr(notifyFn);
     notifyFn(false);
   }
 }
 
 /**
- * TemplateLoader is an asynchronous access to ShadowRoot which is
+ * [TemplateLoader] is an asynchronous access to ShadowRoot which is
  * loaded asynchronously. It allows a Component to be notified when its
  * ShadowRoot is ready.
  */

lib/core_dom/view_factory.dart

@@ -248,7 +248,7 @@ class _AnchorAttrs extends NodeAttrs {
 
   _AnchorAttrs(DirectiveRef this._directiveRef): super(null);
 
-  operator [](name) => name == '.' ? _directiveRef.value : null;
+  DirectiveRef operator [](name) => name == '.' ? _directiveRef.value : null;
 
   void observe(String attributeName, _AttributeChanged notifyFn) {
     notifyFn(attributeName == '.' ? _directiveRef.value : null);