Merge pull request #287 from rwjblue/documentation-updates

Flesh out DOM interaction helper documentation.

addon-test-support/@ember/test-helpers/dom/blur.js

@@ -4,11 +4,6 @@ import settled from '../settled';
 import isFocusable from './-is-focusable';
 import { nextTickPromise } from '../-utils';
 
-/**
-  @private
-  @method __blur__
-  @param {Element} element
-*/
 export function __blur__(element) {
   let browserIsNotFocused = document.hasFocus && !document.hasFocus();
 
@@ -26,10 +21,12 @@ export function __blur__(element) {
 }
 
 /**
-  @method blur
-  @param {String|Element} [target=document.activeElement] the element to blur
-  @return {Promise<void>}
+  Unfocus the specified target.
+
   @public
+  @method blur
+  @param {String|Element} [target=document.activeElement] the element or selector to unfocus
+  @return {Promise<void>} resolves when the application is settled
 */
 export default function blur(target = document.activeElement) {
   return nextTickPromise().then(() => {

addon-test-support/@ember/test-helpers/dom/click.js

@@ -5,11 +5,6 @@ import settled from '../settled';
 import isFocusable from './-is-focusable';
 import { nextTickPromise } from '../-utils';
 
-/**
-  @private
-  @method __click__
-  @param {Element} element
-*/
 export function __click__(element) {
   fireEvent(element, 'mousedown');
 
@@ -22,10 +17,12 @@ export function __click__(element) {
 }
 
 /**
-  @method click
-  @param {String|Element} target
-  @return {Promise<void>}
+  Clicks on the specified target.
+
   @public
+  @method click
+  @param {String|Element} target the element or selector to click on
+  @return {Promise<void>} resolves when the application is settled
 */
 export default function click(target) {
   return nextTickPromise().then(() => {

addon-test-support/@ember/test-helpers/dom/fill-in.js

@@ -5,12 +5,15 @@ import settled from '../settled';
 import fireEvent from './fire-event';
 import { nextTickPromise } from '../-utils';
 
-/*
-  @method fillIn
-  @param {String|Element} target
-  @param {String} text
-  @return {Promise<void>}
+/**
+  Fill the provided text into the `value` property (or set `.innerHTML` when
+  the target is a content editable element) on the specified target.
+
   @public
+  @method fillIn
+  @param {String|Element} target the element or selector to enter text into
+  @param {String} text the text to fill into the target element
+  @return {Promise<void>} resolves when the application is settled
 */
 export default function fillIn(target, text) {
   return nextTickPromise().then(() => {

addon-test-support/@ember/test-helpers/dom/fire-event.js

@@ -16,23 +16,23 @@ const MOUSE_EVENT_TYPES = [
 const FILE_SELECTION_EVENT_TYPES = ['change'];
 
 /**
-  @method fireEvent
-  @param {Element} element
-  @param {String} type
-  @param {Object} [options]
-  @returns {Event}
+  Internal helper used to build and dispatch events throughout the other DOM helpers.
 
   @private
+  @method fireEvent
+  @param {Element} element the element to dispatch the event to
+  @param {string} eventType the type of event
+  @param {Object} [options] additional properties to be set on the event
 */
-export default function fireEvent(element, type, options = {}) {
+export default function fireEvent(element, eventType, options = {}) {
   if (!element) {
     throw new Error('Must pass an element to `fireEvent`');
   }
 
   let event;
-  if (KEYBOARD_EVENT_TYPES.indexOf(type) > -1) {
-    event = buildKeyboardEvent(type, options);
-  } else if (MOUSE_EVENT_TYPES.indexOf(type) > -1) {
+  if (KEYBOARD_EVENT_TYPES.indexOf(eventType) > -1) {
+    event = buildKeyboardEvent(eventType, options);
+  } else if (MOUSE_EVENT_TYPES.indexOf(eventType) > -1) {
     let rect;
     if (element instanceof Window) {
       rect = element.document.documentElement.getBoundingClientRect();
@@ -53,24 +53,17 @@ export default function fireEvent(element, type, options = {}) {
       clientY: y,
     };
 
-    event = buildMouseEvent(type, merge(simulatedCoordinates, options));
-  } else if (FILE_SELECTION_EVENT_TYPES.indexOf(type) > -1 && element.files) {
-    event = buildFileEvent(type, element, options);
+    event = buildMouseEvent(eventType, merge(simulatedCoordinates, options));
+  } else if (FILE_SELECTION_EVENT_TYPES.indexOf(eventType) > -1 && element.files) {
+    event = buildFileEvent(eventType, element, options);
   } else {
-    event = buildBasicEvent(type, options);
+    event = buildBasicEvent(eventType, options);
   }
 
   element.dispatchEvent(event);
   return event;
 }
 
-/**
-  @method buildBasicEvent
-  @param {String} type
-  @param {Object} [options]
-  @return {Event}
-  @private
-*/
 function buildBasicEvent(type, options = {}) {
   let event = document.createEvent('Events');
 
@@ -87,13 +80,6 @@ function buildBasicEvent(type, options = {}) {
   return event;
 }
 
-/**
-  @method buildMouseEvent
-  @param {String} type
-  @param {Object} [options]
-  @return {Event}
-  @private
-*/
 function buildMouseEvent(type, options = {}) {
   let event;
   try {
@@ -122,13 +108,6 @@ function buildMouseEvent(type, options = {}) {
   return event;
 }
 
-/**
-  @method buildKeyboardEvent
-  @param {String} type
-  @param {Object} (optional) options
-  @return {Event}
-  @private
-*/
 function buildKeyboardEvent(type, options = {}) {
   let eventOpts = merge(merge({}, DEFAULT_EVENT_OPTIONS), options);
   let event, eventMethodName;
@@ -197,14 +176,6 @@ function buildKeyboardEvent(type, options = {}) {
   return event;
 }
 
-/**
-  @method buildFileEvent
-  @param {String} type
-  @param {Element} element
-  @param {Array} [files] array of files
-  @return {Event}
-  @private
-*/
 function buildFileEvent(type, element, files = []) {
   let event = buildBasicEvent(type);
 

addon-test-support/@ember/test-helpers/dom/focus.js

@@ -4,11 +4,6 @@ import settled from '../settled';
 import isFocusable from './-is-focusable';
 import { nextTickPromise } from '../-utils';
 
-/**
-  @private
-  @method __focus__
-  @param {Element} element
-*/
 export function __focus__(element) {
   let browserIsNotFocused = document.hasFocus && !document.hasFocus();
 
@@ -29,10 +24,12 @@ export function __focus__(element) {
 }
 
 /**
-  @method focus
-  @param {String|Element} target
-  @return {Promise<void>}
+  Focus the specified target.
+
   @public
+  @method focus
+  @param {String|Element} target the element or selector to focus
+  @return {Promise<void>} resolves when the application is settled
 */
 export default function focus(target) {
   return nextTickPromise().then(() => {

addon-test-support/@ember/test-helpers/dom/tap.js

@@ -4,12 +4,14 @@ import { __click__ } from './click';
 import settled from '../settled';
 import { nextTickPromise } from '../-utils';
 
-/*
-  @method tap
-  @param {String|Element} target
-  @param {Object} options
-  @return {Promise}
+/**
+  Taps on the specified target.
+
   @public
+  @method tap
+  @param {String|Element} target the element or selector to tap on
+  @param {Object} options the options to be provided to the touch events
+  @return {Promise<void>} resolves when the application is settled
 */
 export default function tap(target, options = {}) {
   return nextTickPromise().then(() => {

addon-test-support/@ember/test-helpers/dom/trigger-event.js

@@ -4,14 +4,16 @@ import settled from '../settled';
 import { nextTickPromise } from '../-utils';
 
 /**
-  @method triggerEvent
-  @param {String|Element} target
-  @param {String} eventType
-  @param {Object} options
-  @return {Promise<void>}
+  Triggers an event on the specified target.
+
   @public
+  @method triggerEvent
+  @param {String|Element} target the element or selector to trigger the event on
+  @param {String} eventType the type of event to trigger
+  @param {Object} options additional properties to be set on the event
+  @return {Promise<void>} resolves when the application is settled
 */
-export default function triggerEvent(target, type, options) {
+export default function triggerEvent(target, eventType, options) {
   return nextTickPromise().then(() => {
     if (!target) {
       throw new Error('Must pass an element or selector to `triggerEvent`.');
@@ -22,11 +24,11 @@ export default function triggerEvent(target, type, options) {
       throw new Error(`Element not found when calling \`triggerEvent('${target}', ...)\`.`);
     }
 
-    if (!type) {
+    if (!eventType) {
       throw new Error(`Must provide an \`eventType\` to \`triggerEvent\``);
     }
 
-    fireEvent(element, type, options);
+    fireEvent(element, eventType, options);
 
     return settled();
   });

addon-test-support/@ember/test-helpers/dom/trigger-key-event.js

@@ -13,16 +13,18 @@ const DEFAULT_MODIFIERS = Object.freeze({
 });
 
 /**
+  Triggers a keyboard event on the specified target.
+
   @public
-  @param {String|Element} target
-  @param {'keydown' | 'keyup' | 'keypress'} eventType
-  @param {String} keyCode
-  @param {Object} [modifiers]
-  @param {Boolean} [modifiers.ctrlKey=false]
-  @param {Boolean} [modifiers.altKey=false]
-  @param {Boolean} [modifiers.shiftKey=false]
-  @param {Boolean} [modifiers.metaKey=false]
-  @return {Promise<void>}
+  @param {String|Element} target the element or selector to trigger the event on
+  @param {'keydown' | 'keyup' | 'keypress'} eventType the type of event to trigger
+  @param {String} keyCode the keyCode of the event being triggered
+  @param {Object} [modifiers] the state of various modifier keys
+  @param {boolean} [modifiers.ctrlKey=false] if true the generated event will indicate the control key was pressed during the key event
+  @param {boolean} [modifiers.altKey=false] if true the generated event will indicate the alt key was pressed during the key event
+  @param {boolean} [modifiers.shiftKey=false] if true the generated event will indicate the shift key was pressed during the key event
+  @param {boolean} [modifiers.metaKey=false] if true the generated event will indicate the meta key was pressed during the key event
+  @return {Promise<void>} resolves when the application is settled
 */
 export default function triggerKeyEvent(target, eventType, keyCode, modifiers = DEFAULT_MODIFIERS) {
   return nextTickPromise().then(() => {

addon-test-support/@ember/test-helpers/dom/wait-for.js

@@ -13,31 +13,35 @@ function toArray(nodelist) {
 }
 
 /**
+  Used to wait for a particular selector to appear in the DOM. Due to the fact
+  that it does not wait for general settledness, this is quite useful for testing
+  interim DOM states (e.g. loading states, pending promises, etc).
+
   @method waitFor
-  @param {string|Element} target
-  @param {Object} [options]
-  @param {number} [options.timeout=1000]
-  @param {number} [options.count=1]
-  @returns {Element|Array<Element>}
+  @param {string} selector the selector to wait for
+  @param {Object} [options] the options to be used
+  @param {number} [options.timeout=1000] the time to wait (in ms) for a match
+  @param {number} [options.count=1] the number of elements that should match the provided selector
+  @returns {Element|Array<Element>} the element (or array of elements) that were being waited upon
 */
-export default function waitFor(target, { timeout = 1000, count = null } = {}) {
+export default function waitFor(selector, { timeout = 1000, count = null } = {}) {
   return nextTickPromise().then(() => {
-    if (!target) {
-      throw new Error('Must pass an element or selector to `waitFor`.');
+    if (!selector) {
+      throw new Error('Must pass a selector to `waitFor`.');
     }
 
     let callback;
     if (count !== null) {
       callback = () => {
         let context = getContext();
         let rootElement = context && context.element;
-        let elements = rootElement.querySelectorAll(target);
+        let elements = rootElement.querySelectorAll(selector);
         if (elements.length === count) {
           return toArray(elements);
         }
       };
     } else {
-      callback = () => getElement(target);
+      callback = () => getElement(selector);
     }
     return waitUntil(callback, { timeout });
   });