Improve API docs (selector, binder)

lib/core_dom/element_binder.dart

@@ -124,7 +124,7 @@ class ElementBinder {
     dstPathFn.assign(controller, _parser(expression).bind(scope.context, ScopeLocals.wrapper));
   }
 
-  _createAttrMappings(controller, scope, List<MappingParts> mappings, nodeAttrs, formatters, tasks) {
+  _createAttrMappings(directive, scope, List<MappingParts> mappings, nodeAttrs, formatters, tasks) {
     mappings.forEach((MappingParts p) {
       var attrName = p.attrName;
       var dstExpression = p.dstExpression;
@@ -140,11 +140,11 @@ class ElementBinder {
       if (bindAttr != null) {
         if (p.mode == '<=>') {
           _bindTwoWay(tasks, bindAttr, scope, dstPathFn,
-              controller, formatters, dstExpression);
+              directive, formatters, dstExpression);
         } else if(p.mode == '&') {
-          _bindCallback(dstPathFn, controller, bindAttr, scope);
+          _bindCallback(dstPathFn, directive, bindAttr, scope);
         } else {
-          _bindOneWay(tasks, bindAttr, scope, dstPathFn, controller, formatters);
+          _bindOneWay(tasks, bindAttr, scope, dstPathFn, directive, formatters);
         }
         return;
       }
@@ -153,7 +153,7 @@ class ElementBinder {
         case '@': // string
           var taskId = tasks.registerTask();
           nodeAttrs.observe(attrName, (value) {
-            dstPathFn.assign(controller, value);
+            dstPathFn.assign(directive, value);
             tasks.completeTask(taskId);
           });
           break;
@@ -162,13 +162,13 @@ class ElementBinder {
           if (nodeAttrs[attrName] == null) return;
 
           _bindTwoWay(tasks, nodeAttrs[attrName], scope, dstPathFn,
-              controller, formatters, dstExpression);
+              directive, formatters, dstExpression);
           break;
 
         case '=>': // one-way
           if (nodeAttrs[attrName] == null) return;
           _bindOneWay(tasks, nodeAttrs[attrName], scope,
-              dstPathFn, controller, formatters);
+              dstPathFn, directive, formatters);
           break;
 
         case '=>!': //  one-way, one-time
@@ -177,14 +177,14 @@ class ElementBinder {
           Expression attrExprFn = _parser(nodeAttrs[attrName]);
           var watch;
           watch = scope.watch(nodeAttrs[attrName], (value, _) {
-            if (dstPathFn.assign(controller, value) != null) {
+            if (dstPathFn.assign(directive, value) != null) {
               watch.remove();
             }
           }, formatters: formatters);
           break;
 
         case '&': // callback
-          _bindCallback(dstPathFn, controller, nodeAttrs[attrName], scope);
+          _bindCallback(dstPathFn, directive, nodeAttrs[attrName], scope);
           break;
       }
     });
@@ -196,24 +196,24 @@ class ElementBinder {
       try {
         var linkMapTimer;
         assert((linkTimer = _perf.startTimer('ng.view.link', ref.type)) != false);
-        var controller = nodeInjector.get(ref.type);
-        probe.directives.add(controller);
+        var directive = nodeInjector.get(ref.type);
+        probe.directives.add(directive);
         assert((linkMapTimer = _perf.startTimer('ng.view.link.map', ref.type)) != false);
 
         if (ref.annotation is Controller) {
-          scope.context[(ref.annotation as Controller).publishAs] = controller;
+          scope.context[(ref.annotation as Controller).publishAs] = directive;
         }
 
-        var tasks = new _TaskList(controller is AttachAware ? () {
-          if (scope.isAttached) controller.attach();
+        var tasks = new _TaskList(directive is AttachAware ? () {
+          if (scope.isAttached) directive.attach();
         } : null);
 
         if (ref.mappings.isNotEmpty) {
           if (nodeAttrs == null) nodeAttrs = new _AnchorAttrs(ref);
-          _createAttrMappings(controller, scope, ref.mappings, nodeAttrs, formatters, tasks);
+          _createAttrMappings(directive, scope, ref.mappings, nodeAttrs, formatters, tasks);
         }
 
-        if (controller is AttachAware) {
+        if (directive is AttachAware) {
           var taskId = tasks.registerTask();
           Watch watch;
           watch = scope.watch('1', // Cheat a bit.
@@ -225,8 +225,8 @@ class ElementBinder {
 
         tasks.doneRegistering();
 
-        if (controller is DetachAware) {
-          scope.on(ScopeEvent.DESTROY).listen((_) => controller.detach());
+        if (directive is DetachAware) {
+          scope.on(ScopeEvent.DESTROY).listen((_) => directive.detach());
         }
 
         assert(_perf.stopTimer(linkMapTimer) != false);

lib/core_dom/element_binder_builder.dart

@@ -19,6 +19,7 @@ class ElementBinderFactory {
       new ElementBinder(_perf, _expando, _parser, _componentFactory,
           _transcludingComponentFactory, _shadowDomComponentFactory,
           b.component, b.decorators, b.onEvents, b.bindAttrs, b.childMode);
+
   TemplateElementBinder templateBinder(ElementBinderBuilder b, ElementBinder transclude) =>
       new TemplateElementBinder(_perf, _expando, _parser, _componentFactory,
           _transcludingComponentFactory, _shadowDomComponentFactory,
@@ -34,20 +35,29 @@ class ElementBinderBuilder {
 
   ElementBinderFactory _factory;
 
+  /// "on-*" attribute names and values, added by a [DirectiveSelector]
   final onEvents = <String, String>{};
+  /// "bind-*" attribute names and values, added by a [DirectiveSelector]
   final bindAttrs = <String, String>{};
 
   var decorators = <DirectiveRef>[];
   DirectiveRef template;
-  ViewFactory templateViewFactory;
-
   DirectiveRef component;
 
   // Can be either COMPILE_CHILDREN or IGNORE_CHILDREN
   String childMode = Directive.COMPILE_CHILDREN;
 
   ElementBinderBuilder(this._factory);
 
+  /**
+   * Adds [DirectiveRef]s to this [ElementBinderBuilder].
+   *
+   * [addDirective] gets called from [Selector.matchElement] for each directive triggered by the
+   * element.
+   *
+   * When the [Directive] annotation defines a `map`, the attribute mappings are added to the
+   * [DirectiveRef].
+   */
   addDirective(DirectiveRef ref) {
     var annotation = ref.annotation;
     var children = annotation.children;
@@ -78,14 +88,9 @@ class ElementBinderBuilder {
     });
   }
 
+  /// Creates an returns an [ElementBinder] or a [TemplateElementBinder]
   ElementBinder get binder {
-    if (template != null) {
-      var transclude = _factory.binder(this);
-      return _factory.templateBinder(this, transclude);
-
-    } else {
-      return _factory.binder(this);
-    }
-
+    var elBinder = _factory.binder(this);
+    return template == null ? elBinder : _factory.templateBinder(this, elBinder);
   }
 }

lib/core_dom/selector.dart

@@ -1,26 +1,24 @@
 part of angular.core.dom_internal;
 
 /**
- * DirectiveSelector is a function which given a node it will return a
- * list of [DirectiveRef]s which are triggered by this node.
+ * [DirectiveSelector] is used by the [Compiler] during the template walking to extract the
+ * [DirectiveRef]s.
  *
- * DirectiveSelector is used by the [Compiler] during the template walking
- * to extract the [DirectiveRef]s.
+ * [DirectiveSelector] can be created using the [DirectiveSelectorFactory].
  *
- * DirectiveSelector can be created using the [DirectiveSelectorFactory].
- *
- * The DirectiveSelector supports CSS selectors which do not cross
- * element boundaries only. The selectors can have any mix of element-name,
- * class-names and attribute-names.
+ * The DirectiveSelector supports CSS selectors which do not cross element boundaries only. The
+ * selectors can have any mix of element-name, class-names and attribute-names.
  *
  * Examples:
  *
  *  * element
  *  * .class
  *  * [attribute]
  *  * [attribute=value]
+ *  * [wildcard-*]
  *  * element[attribute1][attribute2=value]
  *  * :contains(/abc/)
+ *  * [*=/abc/]
  */
 class DirectiveSelector {
   ElementBinderFactory _binderFactory;
@@ -29,6 +27,7 @@ class DirectiveSelector {
   var attrSelector;
   var textSelector;
 
+  /// Parses all the [_directives] so they can be retrieved via [matchElement]
   DirectiveSelector(this._directives, this._binderFactory) {
     elementSelector = new _ElementSelector('');
     attrSelector = <_ContainsSelector>[];
@@ -54,6 +53,10 @@ class DirectiveSelector {
     });
   }
 
+  /**
+   * [matchElement] returns an [ElementBinder] or a [TemplateElementBinder] configured with all the
+   * directives triggered by the `node`.
+   */
   ElementBinder matchElement(dom.Node node) {
     assert(node is dom.Element);
 
@@ -143,8 +146,7 @@ class DirectiveSelector {
     return builder.binder;
   }
 
-  ElementBinder matchComment(dom.Node node) =>
-      _binderFactory.builder().binder;
+  ElementBinder matchComment(dom.Node node) => _binderFactory.builder().binder;
 }
 
 /**