From 43edb22991d3e12b092cba2de825847297df80ca Mon Sep 17 00:00:00 2001
From: Marko Vuksanovic <markovuksanovic@gmail.com>
Date: Wed, 19 Mar 2014 22:26:39 +1100
Subject: [PATCH] docs(EventHandler): Add EventHandler documentation.

Add documentation to EventHandler. This change also makes fields and methods within EventHandler, which are not intended for public use, private.
---
 lib/core_dom/event_handler.dart | 58 ++++++++++++++++++++++++---------
 1 file changed, 43 insertions(+), 15 deletions(-)

diff --git a/lib/core_dom/event_handler.dart b/lib/core_dom/event_handler.dart
index 0ca4ba46d..113212c62 100644
--- a/lib/core_dom/event_handler.dart
+++ b/lib/core_dom/event_handler.dart
@@ -2,45 +2,73 @@ part of angular.core.dom;
 
 typedef void EventFunction(event);
 
+/**
+ * [EventHandler] is responsible for handling events bound using on-* syntax
+ * (i.e. `on-click="ctrl.doSomething();"`). The root of the application has an
+ * EventHandler attached as does every [NgComponent].
+ *
+ * Events bound within [NgComponent] are handled by EventHandler attached to
+ * their [ShadowRoot]. All other events are handled by EventHandler attached
+ * to the application root ([NgApp]).
+ *
+ * **Note**: The expressions are executed within the closest context.
+ *
+ * Example:
+ *
+ *     <div foo>
+ *       <button on-click="ctrl.say('Hello');">Button</button>;
+ *     </div>
+ *
+ *     @NgComponent(selector: '[foo]', publishAs: ctrl)
+ *     class FooController {
+ *       say(String something) => print(something);
+ *     }
+ *
+ * When button is clicked, "Hello" will be printed in the console.
+ */
 @NgInjectableService()
 class EventHandler {
-  dom.Node rootNode;
-  final Expando expando;
-  final ExceptionHandler exceptionHandler;
-  final listeners = <String, Function>{};
+  dom.Node _rootNode;
+  final Expando _expando;
+  final ExceptionHandler _exceptionHandler;
+  final _listeners = <String, Function>{};
 
-  EventHandler(this.rootNode, this.expando, this.exceptionHandler);
+  EventHandler(this._rootNode, this._expando, this._exceptionHandler);
 
+  /**
+   * Register an event. This makes sure that  an event (of the specified name)
+   * which bubbles to this node, gets processed by this [EventHandler].
+   */
   void register(String eventName) {
-    listeners.putIfAbsent(eventName, () {
-      dom.EventListener eventListener = this.eventListener;
-      rootNode.on[eventName].listen(eventListener);
+    _listeners.putIfAbsent(eventName, () {
+      dom.EventListener eventListener = this._eventListener;
+      _rootNode.on[eventName].listen(eventListener);
       return eventListener;
     });
   }
 
-  void eventListener(dom.Event event) {
+  void _eventListener(dom.Event event) {
     dom.Node element = event.target;
-    while (element != null && element != rootNode) {
+    while (element != null && element != _rootNode) {
       var expression;
       if (element is dom.Element)
         expression = (element as dom.Element).attributes[eventNameToAttrName(event.type)];
       if (expression != null) {
         try {
-          var scope = getScope(element);
+          var scope = _getScope(element);
           if (scope != null) scope.eval(expression);
         } catch (e, s) {
-          exceptionHandler(e, s);
+          _exceptionHandler(e, s);
         }
       }
       element = element.parentNode;
     }
   }
 
-  Scope getScope(dom.Node element) {
+  Scope _getScope(dom.Node element) {
     // var topElement = (rootNode is dom.ShadowRoot) ? rootNode.parentNode : rootNode;
-    while (element != rootNode.parentNode) {
-      ElementProbe probe = expando[element];
+    while (element != _rootNode.parentNode) {
+      ElementProbe probe = _expando[element];
       if (probe != null) {
         return probe.scope;
       }