Merge pull request #47 from canjs/docs

improved docs #46

.npmrc

@@ -0,0 +1 @@
+package-lock=false

can-dom-events.js

@@ -5,45 +5,23 @@ var util = require('./helpers/util');
 var makeEventRegistry = require('./helpers/make-event-registry');
 var makeDelegateEventTree = require('./helpers/-make-delegate-event-tree');
 
-/**
- * @module {{}} can-dom-events
- * @parent can-dom-utilities
- * @collection can-infrastructure
- * @package ./package.json
- * @description Dispatch and listen to DOM Events.
- * @group can-dom-events.static 0 static
- * @group can-dom-events.helpers 1 helpers
- * @group can-dom-events.types 2 types
- * @signature `domEvents`
- *
- * @body
- *
- * ```js
- * var domEvents = require("can-dom-events");
- * var input = document.createElement('input');
- *
- * function onChange(event) {
- * 	console.log('Input value changed to:', event.target.value);
- * }
- *
- * domEvents.addEventListener(input, 'change', onChange);
- *
- * domEvents.dispatch(input, 'change'); // calls onChange
- *
- * domEvents.removeEventListener(input, 'change', onChange);
- * ```
- */
+
 var domEvents = {
 	_eventRegistry: makeEventRegistry(),
 
 	/**
 	* @function can-dom-events.addEvent addEvent
+	* @parent can-dom-events.static
 	*
 	* Add a custom event to the global event registry.
 	*
 	* @signature `addEvent( event [, eventType ] )`
-	* @parent can-dom-events.static
-	* @param {EventDefinition} event The custom event definition.
+	*
+	* ```js
+	* var removeReturnEvent = domEvents.addEvent(enterEvent, "return");
+	* ```
+	*
+	* @param {can-dom-events/EventDefinition} event The custom event definition.
 	* @param {String} eventType The event type to associated with the custom event.
 	* @return {function} The callback to remove the custom event from the registry.
 	*/
@@ -60,7 +38,8 @@ var domEvents = {
 	* @parent can-dom-events.static
 	* @param {DomEventTarget} target The object to which to add the listener.
 	* @param {String} eventType The event type with which to register.
-	* @param {*} eventArgs The arguments which configure the associated event's behavior.
+	* @param {*} eventArgs The arguments which configure the associated event's behavior. This is usually a
+	* function event handler.
 	*/
 	addEventListener: function(target, eventType) {
 		var hasCustomEvent = domEvents._eventRegistry.has(eventType);
@@ -82,7 +61,8 @@ var domEvents = {
 	* @parent can-dom-events.static
 	* @param {DomEventTarget} target The object to which to add the listener.
 	* @param {String} eventType The event type with which to unregister.
-	* @param {*} eventArgs The arguments which configure the associated event's behavior.
+	* @param {*} eventArgs The arguments which configure the associated event's behavior. This is usually a
+	* function event handler.
 	*/
 	removeEventListener: function(target, eventType) {
 		var hasCustomEvent = domEvents._eventRegistry.has(eventType);
@@ -95,11 +75,51 @@ var domEvents = {
 		return target.removeEventListener.apply(target, eventArgs);
 	},
 
-
-	addDelegateListener: function(target, eventType, selector, handler) {
-		domEvents._eventTree.add([target, eventType, selector, handler]);
+	/**
+	* @function can-dom-events.addDelegateListener addDelegateListener
+	*
+	* Attach a handler for an event for all elements that match the selector,
+	* now or in the future, based on a root element.
+	*
+	* @signature `addDelegateListener( target, eventType, selector, handler )`
+	*
+	* ```js
+	* // Prevents all anchor elements from changing the page
+	* domEvents.addDelegateListener(document.body,"click", "a", function(event){
+	*   event.preventDefault();
+	* })
+	* ```
+	* @parent can-dom-events.static
+	* @param {DomEventTarget} root The html element to listen to events that match selector within.
+	* @param {String} eventType The event name to listen to.
+	* @param {String} selector A selector to filter the elements that trigger the event.
+	* @param {function} handler A function to execute at the time the event is triggered.
+	*/
+	addDelegateListener: function(root, eventType, selector, handler) {
+		domEvents._eventTree.add([root, eventType, selector, handler]);
 	},
-
+	/**
+	* @function can-dom-events.removeDelegateListener removeDelegateListener
+	*
+	* Remove a handler for an event for all elements that match the selector.
+	*
+	* @signature `removeDelegateListener( target, eventType, selector, handler )`
+	*
+	* ```js
+	* // Prevents all anchor elements from changing the page
+	* function handler(event) {
+	*   event.preventDefault();
+	* }
+	* domEvents.addDelegateListener(document.body,"click", "a", handler);
+	*
+	* domEvents.removeDelegateListener(document.body,"click", "a", handler);
+	* ```
+	* @parent can-dom-events.static
+	* @param {DomEventTarget} root The html element to listen to events that match selector within.
+	* @param {String} eventType The event name to listen to.
+	* @param {String} selector A selector to filter the elements that trigger the event.
+	* @param {function} handler A function that was previously passed to `addDelegateListener`.
+	*/
 	removeDelegateListener: function(target, eventType, selector, handler) {
 		domEvents._eventTree.delete([target, eventType, selector, handler]);
 	},
@@ -135,37 +155,8 @@ var domEvents = {
 
 domEvents._eventTree = makeDelegateEventTree(domEvents);
 
-/**
- * @typedef {Object} can-dom-events.EventDefinition EventDefinition
- * @description Definition of a custom event that may be added to an event registry.
- * @parent can-dom-events.types
- * @type {Object}
- *     @option {String} [defaultEventType]
- *     The default event type of the event.
- *
- *     @option {function} [addEventListener]
- *     The function to add the listener to the target.
- *         @param {DomEventTarget} target The target to which to add the listener.
- *         @param {String} eventType The event type which should be used to register the listener.
- *         @param {*} eventArgs The arguments should to configure the listener behavior.
- *
- *     @option {function} [removeEventListener]
- *     The function to remove the listener from the target.
- *         @param {DomEventTarget} target The target to which to add the listener.
- *         @param {String} eventType The event type which should be used to register the listener.
- *         @param {*} eventArgs The arguments should to configure the listener behavior.
- */
-
- /**
- * @typedef {Object} can-dom-events.DomEventTarget DomEventTarget
- * @description
- * An object which can have DOM Events registered on it.
- * This is a Window, Document, or HTMLElement.
- * @parent can-dom-events.types
- * @signature `Window|Document|HTMLElement`
- * @type {Window}
- * @type {Document}
- * @type {HTMLElement}
- */
+
+
+
 
 module.exports = namespace.domEvents = domEvents;

doc/can-dom-events.md

@@ -0,0 +1,84 @@
+@module {can-dom-events/EventRegistry} can-dom-events
+@parent can-dom-utilities
+@collection can-infrastructure
+@package ../package.json
+@group can-dom-events.static 0 static
+@group can-dom-events.types 1 types
+
+@description Listen to DOM events and special events, and register
+special events.
+
+@type {can-dom-events/EventRegistry}
+  The `can-dom-events` module exports the _global_ event registry.  Use
+  it to listen to DOM events on HTML elements.  Any custom event
+  types added to this registry are available to every other part of CanJS.
+
+
+@body
+
+## Use
+
+The following listens to a 'change' event on an element:
+
+```js
+var domEvents = require("can-dom-events");
+var input = document.createElement('input');
+
+function onChange(event) {
+    console.log('Input value changed to:', event.target.value);
+}
+
+domEvents.addEventListener(input, 'change', onChange);
+```
+
+Use [can-dom-events.dispatch] to fire custom events:
+```js
+domEvents.dispatch(input, 'change');
+```
+
+Use [can-dom-events.addDelegateListener] to listen to an event for all elements that
+match a selector within a root element:
+
+```js
+domEvents.addDelegateListener(document.body,"click", "a", function(event){
+  event.preventDefault();
+});
+```
+
+Finally, you can create your own custom events and add them to
+the global event registry. First, create an [can-dom-events/EventDefinition]
+object. For example, the following might implement
+an "escape" event that listens to when a user presses the `Escape` key:
+
+
+```js
+var handlerMap = new WeakMap();
+var escapeEventDefinition = {
+    defaultEventType: 'escape',
+    addEventListener: function (target, eventType, handler) {
+        var keyHandler = function (event) {
+        	if (event.keyCode === 27 || event.key === 'Escape') {
+        		return handler.apply(this, arguments);
+        	}
+        };
+        handlerMap.set(handler, keyHandler)
+        this.addEventListener(target, baseEventType, keyHandler);
+    },
+    removeEventListener: function (target, eventType, handler) {
+        this.removeEventListener(target, baseEventType, handlerMap.get(handler));
+    }
+}
+```
+
+Then you can add this custom event to the registry and listen to that event:
+
+```js
+import domEvents from "can-dom-events";
+
+domEvents.addEvent(escapeEventDefinition);
+
+var input = document.querySelector("[name=search]");
+domEvents.addEventListener(input, "escape", function(){
+
+});
+```

doc/dom-event-target.md

@@ -0,0 +1,11 @@
+@typedef {Object} can-dom-events.DomEventTarget DomEventTarget
+@parent can-dom-events.types
+
+@description An object which can have DOM Events registered on it.
+This is a Window, Document, or HTMLElement.
+
+@signature `Window|Document|HTMLElement`
+
+@type {Window}
+@type {Document}
+@type {HTMLElement}

doc/event-definition.md

@@ -0,0 +1,18 @@
+@typedef {Object} can-dom-events/EventDefinition EventDefinition
+@description Definition of a custom event that may be added to an event registry.
+@parent can-dom-events.types
+@type {Object}
+    @option {String} [defaultEventType]
+    The default event type of the event.
+
+    @option {function} [addEventListener]
+    The function to add the listener to the target.
+        @param {DomEventTarget} target The target to which to add the listener.
+        @param {String} eventType The event type which should be used to register the listener.
+        @param {*} eventArgs The arguments should to configure the listener behavior.
+
+    @option {function} [removeEventListener]
+    The function to remove the listener from the target.
+        @param {DomEventTarget} target The target to which to add the listener.
+        @param {String} eventType The event type which should be used to register the listener.
+        @param {*} eventArgs The arguments should to configure the listener behavior.

doc/event-registry.md

@@ -0,0 +1,4 @@
+@typedef {Object} can-dom-events/EventRegistry EventRegistry
+@parent can-dom-events.types
+@hide 
+@description Blah

helpers/make-event-registry.js

@@ -8,9 +8,10 @@ function EventRegistry () {
  * @module can-dom-events/helpers/make-event-registry
  * @parent can-dom-events.helpers
  * @description Create an event registry.
- * @group make-event-registry.registry 0 EventRegistry
  * @signature `makeEventRegistry()`
- *
+ *   @return {can-dom-events/EventRegistry}
+ * @hide
+ * 
  * @body
  *
  * ```js
@@ -36,7 +37,7 @@ module.exports = function makeEventRegistry () {
  * Check whether an event type has already been registered.
  *
  * @signature `eventRegistry.has( eventType )`
- * @parent make-event-registry.registry
+ * @parent can-dom-events/EventRegistry
  * @param {String} eventType The event type for which to check.
  * @return {Boolean} Whether the event type is registered.
 */
@@ -50,7 +51,7 @@ EventRegistry.prototype.has = function (eventType) {
  * Retrieve an event type which has already been registered.
  *
  * @signature `eventRegistry.get( eventType )`
- * @parent make-event-registry.registry
+ * @parent can-dom-events/EventRegistry
  * @param {String} eventType The event type for which to retrieve.
  * @return {EventDefinition} The registered event definition, or undefined if unregistered.
 */
@@ -64,7 +65,7 @@ EventRegistry.prototype.get = function (eventType) {
  * Add an event to the registry.
  *
  * @signature `eventRegistry.add( event [, eventType ] )`
- * @parent make-event-registry.registry
+ * @parent can-dom-events/EventRegistry
  * @param {EventDefinition} event The event definition to register.
  * @param {String} eventType The event type with which to register the event.
  * @return {function} The callback to remove the event from the registry.