Specs: clean up event listeners a bit. Drop the pointless

sky/specs/apis.md

 APIs
 ====
 
 The Sky core API
 ----------------
 
 ```javascript
 module 'sky:core' {
 
   // EVENTS
 
   class Event {
     constructor (String type, Boolean bubbles = true, any data = null); // O(1)
     readonly attribute String type; // O(1)
     readonly attribute Boolean bubbles; // O(1)
     attribute any data; // O(1)
 
     readonly attribute EventTarget target; // O(1)
-    void preventDefault(); // O(1)
-    attribute any result; // O(1) // defaults to undefined
+    attribute Boolean handled; // O(1)
+    attribute any result; // O(1)
 
     // TODO(ianh): do events get blocked at scope boundaries, e.g. focus events when both sides are in the scope?
-    // TODO(ianh): do events ger retargetted, e.g. focus when leaving a custom element?
+    // TODO(ianh): do events get retargetted, e.g. focus when leaving a custom element?
   }
 
-  callback EventListener any (Event event); // return value is assigned to Event.result
+  callback EventListener any (Event event);
+    // if the return value is not undefined:
+    //   assign it to event.result
+    //   set event.handled to true
 
   abstract class EventTarget {
-    any dispatchEvent(Event event); // O(N) in total number of listeners for this type in the chain // returns Event.result
+    any dispatchEvent(Event event); // O(N) in total number of listeners for this type in the chain
+      // sets event.handled to false and event.result to undefined
+      // makes a record of the event target chain
+      // invokes all the handlers on the chain in turn
+      // returns event.result
     void addEventListener(String type, EventListener listener); // O(1)
     void removeEventListener(String type, EventListener listener); // O(N) in event listeners with that type
     private Array<String> getRegisteredEventListenerTypes(); // O(N)
     private Array<EventListener> getRegisteredEventListenersForType(String type); // O(N)
   }
 
   class CustomEventTarget : EventTarget {
     constructor (); // O(1)
     attribute EventTarget parentNode; // getter O(1), setter O(N) in height of tree, throws if this would make a loop
 
@@ skipping 455 matching lines @@
   the core mojo fabric JS API   sky:mojo:fabric:core
   the asyncWait/cancelWait mojo fabric JS API (interface to IPC thread)  sky:mojo:fabric:ipc
   the mojom for the shell, proxying through C++ so that the shell pipe isn't exposed  sky:mojo:shell
   the sky API  sky:core
   the sky debug symbols for private APIs  sky:debug
 ```
 
 TODO(ianh): determine if we want to separate the "this" from the
 Document, especially for Modules, so that exposing a module's element
 doesn't expose the module's exports attribute.