doc(selector): improve api doc

Closes #1038

Author: vicb

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;
 }
 
 /**