docs: add doc to event-management api (#23656)

PR Close #23656

packages/platform-browser/src/dom/events/event_manager.ts

@@ -10,29 +10,60 @@ import {Inject, Injectable, InjectionToken, NgZone} from '@angular/core';
 
 import {getDOM} from '../dom_adapter';
 
+/**
+ * The injection token for the event-manager plug-in service.
+ */
 export const EVENT_MANAGER_PLUGINS =
     new InjectionToken<EventManagerPlugin[]>('EventManagerPlugins');
 
+/**
+ * An injectable service that provides event management for Angular
+ * through a browser plug-in.
+ */
 @Injectable()
 export class EventManager {
   private _plugins: EventManagerPlugin[];
   private _eventNameToPlugin = new Map<string, EventManagerPlugin>();
 
+  /**
+   * Initializes an instance of the event-manager service.
+   */
   constructor(@Inject(EVENT_MANAGER_PLUGINS) plugins: EventManagerPlugin[], private _zone: NgZone) {
     plugins.forEach(p => p.manager = this);
     this._plugins = plugins.slice().reverse();
   }
 
+  /**
+   * Registers a handler for a specific element and event.
+   *
+   * @param element The HTML element to receive event notifications.
+   * @param eventName The name of the event to listen for.
+   * @param handler A function to call when the notification occurs. Receives the
+   * event object as an argument.
+   * @returns  A callback function that can be used to remove the handler.
+   */
   addEventListener(element: HTMLElement, eventName: string, handler: Function): Function {
     const plugin = this._findPluginFor(eventName);
     return plugin.addEventListener(element, eventName, handler);
   }
 
+  /**
+   * Registers a global handler for an event in a target view.
+   *
+   * @param target A target for global event notifications. One of "window", "document", or "body".
+   * @param eventName The name of the event to listen for.
+   * @param handler A function to call when the notification occurs. Receives the
+   * event object as an argument.
+   * @returns A callback function that can be used to remove the handler.
+   */
   addGlobalEventListener(target: string, eventName: string, handler: Function): Function {
     const plugin = this._findPluginFor(eventName);
     return plugin.addGlobalEventListener(target, eventName, handler);
   }
 
+  /**
+   * Retrieves the compilation zone in which event listeners are registered.
+   */
   getZone(): NgZone { return this._zone; }
 
   /** @internal */

packages/platform-browser/src/dom/events/hammer_gestures.ts

@@ -12,6 +12,9 @@ import {DOCUMENT} from '../dom_tokens';
 
 import {EventManagerPlugin} from './event_manager';
 
+/**
+ * Supported HammerJS recognizer event names.
+ */
 const EVENT_NAMES = {
   // pan
   'pan': true,
@@ -51,8 +54,8 @@ const EVENT_NAMES = {
 };
 
 /**
- * A DI token that you can use to provide{@link HammerGestureConfig} to Angular. Use it to configure
- * Hammer gestures.
+ * DI token for providing [HammerJS](http://hammerjs.github.io/) support to Angular.
+ * @see `HammerGestureConfig`
  *
  * @experimental
  */
@@ -71,14 +74,44 @@ export interface HammerInstance {
 }
 
 /**
+ * An injectable [HammerJS Manager](http://hammerjs.github.io/api/#hammer.manager)
+ * for gesture recognition. Configures specific event recognition.
  * @experimental
  */
 @Injectable()
 export class HammerGestureConfig {
+  /**
+   * A set of supported event names for gestures to be used in Angular.
+   * Angular supports all built-in recognizers, as listed in
+   * [HammerJS documentation](http://hammerjs.github.io/).
+   */
   events: string[] = [];
 
+  /**
+  * Maps gesture event names to a set of configuration options
+  * that specify overrides to the default values for specific properties.
+  *
+  * The key is a supported event name to be configured,
+  * and the options object contains a set of properties, with override values
+  * to be applied to the named recognizer event.
+  * For example, to disable recognition of the rotate event, specify
+  *  `{"rotate": {"enable": false}}`.
+  *
+  * Properties that are not present take the HammerJS default values.
+  * For information about which properties are supported for which events,
+  * and their allowed and default values, see
+  * [HammerJS documentation](http://hammerjs.github.io/).
+  *
+  */
   overrides: {[key: string]: Object} = {};
 
+  /**
+   * Properties whose default values can be overridden for a given event.
+   * Different sets of properties apply to different events.
+   * For information about which properties are supported for which events,
+   * and their allowed and default values, see
+   * [HammerJS documentation](http://hammerjs.github.io/).
+   */
   options?: {
     cssProps?: any; domEvents?: boolean; enable?: boolean | ((manager: any) => boolean);
     preset?: any[];
@@ -88,8 +121,14 @@ export class HammerGestureConfig {
     inputTarget?: EventTarget;
   };
 
+  /**
+   * Creates a [HammerJS Manager](http://hammerjs.github.io/api/#hammer.manager)
+   * and attaches it to a given HTML element.
+   * @param element The element that will recognize gestures.
+   * @returns A HammerJS event-manager object.
+   */
   buildHammer(element: HTMLElement): HammerInstance {
-    const mc = new Hammer(element, this.options);
+    const mc = new Hammer !(element, this.options);
 
     mc.get('pinch').set({enable: true});
     mc.get('rotate').set({enable: true});

packages/platform-browser/src/dom/events/key_events.ts

@@ -13,7 +13,14 @@ import {DOCUMENT} from '../dom_tokens';
 
 import {EventManagerPlugin} from './event_manager';
 
+/**
+ * Defines supported modifiers for key events.
+ */
 const MODIFIER_KEYS = ['alt', 'control', 'meta', 'shift'];
+
+/**
+ * Retrieves modifiers from key-event objects.
+ */
 const MODIFIER_KEY_GETTERS: {[key: string]: (event: KeyboardEvent) => boolean} = {
   'alt': (event: KeyboardEvent) => event.altKey,
   'control': (event: KeyboardEvent) => event.ctrlKey,
@@ -23,13 +30,31 @@ const MODIFIER_KEY_GETTERS: {[key: string]: (event: KeyboardEvent) => boolean} =
 
 /**
  * @experimental
+ * A browser plug-in that provides support for handling of key events in Angular.
  */
 @Injectable()
 export class KeyEventsPlugin extends EventManagerPlugin {
+  /**
+   * Initializes an instance of the browser plug-in.
+   * @param doc The document in which key events will be detected.
+   */
   constructor(@Inject(DOCUMENT) doc: any) { super(doc); }
 
+  /**
+    * Reports whether a named key event is supported.
+    * @param eventName The event name to query.
+    * @return True if the named key event is supported.
+   */
   supports(eventName: string): boolean { return KeyEventsPlugin.parseEventName(eventName) != null; }
 
+  /**
+   * Registers a handler for a specific element and key event.
+   * @param element The HTML element to receive event notifications.
+   * @param eventName The name of the key event to listen for.
+   * @param handler A function to call when the notification occurs. Receives the
+   * event object as an argument.
+   * @returns The key event that was registered.
+  */
   addEventListener(element: HTMLElement, eventName: string, handler: Function): Function {
     const parsedEvent = KeyEventsPlugin.parseEventName(eventName) !;
 
@@ -93,6 +118,13 @@ export class KeyEventsPlugin extends EventManagerPlugin {
     return fullKey;
   }
 
+  /**
+   * Configures a handler callback for a key event.
+   * @param fullKey The event name that combines all simultaneous keystrokes.
+   * @param handler The function that responds to the key event.
+   * @param zone The zone in which the event occurred.
+   * @returns A callback function.
+   */
   static eventCallback(fullKey: any, handler: Function, zone: NgZone): Function {
     return (event: any /** TODO #9100 */) => {
       if (KeyEventsPlugin.getEventFullKey(event) === fullKey) {