Merge pull request #8 from Turbo87/docs

Generate API docs from JSDoc comments
mainmatter · Oct 8, 2017 · 2ec7ce4 · 2ec7ce4
2 parents e6516a5 + 4733b46
commit 2ec7ce4
Show file tree

Hide file tree

Showing 11 changed files with 1,970 additions and 150 deletions.
diff --git a/API.md b/API.md
@@ -0,0 +1,122 @@
+# API
+
+[htmlelement]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
+
+[nodelist]: https://developer.mozilla.org/en-US/docs/Web/API/NodeList
+
+## assert.dom()
+
+Once installed the DOM element assertions are available at `assert.dom(...).*`:
+
+**Parameters**
+
+-   `target` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/HTML/Element))** A CSS selector that can be used to find elements using [`querySelector()`](https://developer.mozilla.org/de/docs/Web/API/Document/querySelector), or an [HTMLElement][] (Not all assertions support both target types.)
+-   `rootElement` **[HTMLElement](https://developer.mozilla.org/en-US/docs/Web/HTML/Element)?** The root element of the DOM in which to search for the `target` (optional, default `document`)
+
+**Examples**
+
+```javascript
+test('the title exists', function(assert) {
+  assert.dom('#title').exists();
+});
+```
+
+## Assertions
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+### exists
+
+Assert an [HTMLElement][] (or multiple) matching the `selector` exists.
+
+**Parameters**
+
+-   `options` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** 
+-   `message` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** 
+
+**Examples**
+
+```javascript
+assert.dom('#title').exists();
+assert.dom('.choice').exists({ count: 4 });
+```
+
+### missing
+
+Assert an [HTMLElement][] matching the `selector` does not exists.
+
+**Parameters**
+
+-   `message` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** 
+
+**Examples**
+
+```javascript
+assert.dom('.should-not-exist').missing();
+```
+
+### focused
+
+Assert that the [HTMLElement][] or an [HTMLElement][] matching the
+`selector` is currently focused.
+
+**Parameters**
+
+-   `message` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** 
+
+**Examples**
+
+```javascript
+assert.dom('input.email').focused();
+```
+
+### notFocused
+
+Assert that the [HTMLElement][] or an [HTMLElement][] matching the
+`selector` is not currently focused.
+
+**Parameters**
+
+-   `message` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** 
+
+**Examples**
+
+```javascript
+assert.dom('input[type="password"]').notFocused();
+```
+
+### textContains
+
+Assert that the text of the [HTMLElement][] or an [HTMLElement][]
+matching the `selector` contains the given `text`, using the
+[`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)
+attribute.
+
+**Parameters**
+
+-   `text` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** 
+-   `message` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** 
+
+**Examples**
+
+```javascript
+assert.dom('#title').textContains('Welcome');
+```
+
+### textMatches
+
+Assert that the text of the [HTMLElement][] or an [HTMLElement][]
+matching the `selector` matches the given regular expression, using the
+[`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)
+attribute.
+
+**Parameters**
+
+-   `regex` **[RegExp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp)** 
+-   `message` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** 
+
+**Examples**
+
+```javascript
+assert.dom('.foo').textMatches(/[12]\d{3}/);
+```
diff --git a/README.md b/README.md
@@ -49,57 +49,7 @@ test('the title is friendly', function(assert) {
 });
 ```
 
-
-Assertions
-------------------------------------------------------------------------------
-
-### `assert.dom(selector).exists([options], [message])`
-### `assert.dom(selector).missing([message])`
-
-Assert an [HTMLElement][] (or multiple) matching the `selector` exists.
-
-```js
-assert.dom('#title').exists();
-assert.dom('.choice').exists({ count: 4 });
-assert.dom('.should-not-exist').missing();
-```
-
-
-### `assert.dom(selector|element).focused([message])`
-### `assert.dom(selector|element).notFocused([message])`
-
-Assert that the [HTMLElement][] is or is not currently focused.
-
-```js
-assert.dom('input.email').focused();
-assert.dom(document.querySelector('input[type="password"]')).notFocused();
-```
-
-
-### `assert.dom(selector|element).textContains(text, [message])`
-
-Assert that the text of the [HTMLElement][] contains the given `text`, using
-[`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent).
-
-```js
-assert.dom('#title').textContains('Welcome');
-assert.dom(document.querySelector('#title')).textContains('Welcome');
-```
-
-
-### `assert.dom(selector|element).textMatches(regex, [message])`
-
-Assert that the text of the [HTMLElement][] matches the given regular expression, using
-[`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent).
-
-```js
-assert.dom('.foo').textMatches(/[12]\d{3}/);
-assert.dom(document.querySelector('.foo')).textMatches(/[12]\d{3}/);
-```
-
-
-[HTMLElement]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
-[NodeList]: https://developer.mozilla.org/en-US/docs/Web/API/NodeList
+**All available assertions are documented in [API.md](API.md).**
 
 
 Related

diff --git a/lib/assertions.js b/lib/assertions.js
@@ -12,26 +12,86 @@ export default class DOMAssertions {
     this.testContext = testContext;
   }
 
+  /**
+   * Assert an [HTMLElement][] (or multiple) matching the `selector` exists.
+   *
+   * @param {object?} options
+   * @param {string?} message
+   *
+   * @example
+   * assert.dom('#title').exists();
+   * assert.dom('.choice').exists({ count: 4 });
+   */
   exists(options, message) {
     exists.call(this, this.target, options, message);
   }
 
+  /**
+   * Assert an [HTMLElement][] matching the `selector` does not exists.
+   *
+   * @param {string?} message
+   *
+   * @example
+   * assert.dom('.should-not-exist').missing();
+   */
   missing(message) {
     missing.call(this, this.target, message);
   }
 
+  /**
+   * Assert that the [HTMLElement][] or an [HTMLElement][] matching the
+   * `selector` is currently focused.
+   *
+   * @param {string?} message
+   *
+   * @example
+   * assert.dom('input.email').focused();
+   */
   focused(message) {
     focused.call(this, this.target, message);
   }
 
+  /**
+   * Assert that the [HTMLElement][] or an [HTMLElement][] matching the
+   * `selector` is not currently focused.
+   *
+   * @param {string?} message
+   *
+   * @example
+   * assert.dom('input[type="password"]').notFocused();
+   */
   notFocused(message) {
     notFocused.call(this, this.target, message);
   }
 
+  /**
+   * Assert that the text of the [HTMLElement][] or an [HTMLElement][]
+   * matching the `selector` contains the given `text`, using the
+   * [`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)
+   * attribute.
+   *
+   * @param {string} text
+   * @param {string?} message
+   *
+   * @example
+   * assert.dom('#title').textContains('Welcome');
+   */
   textContains(text, message) {
     textContains.call(this, this.target, text, message);
   }
 
+  /**
+   * Assert that the text of the [HTMLElement][] or an [HTMLElement][]
+   * matching the `selector` matches the given regular expression, using the
+   * [`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)
+   * attribute.
+   *
+   * @param {RegExp} regex
+   * @param {string?} message
+   *
+   * @example
+   * assert.dom('.foo').textMatches(/[12]\d{3}/);
+   */
   textMatches(regex, message) {
     textMatches.call(this, this.target, regex, message);
   }

diff --git a/lib/assertions/exists.js b/lib/assertions/exists.js
@@ -1,10 +1,3 @@
-/**
- * Asserts that the passed in DOM element exists.
- *
- * @param {string} selector
- * @param {object?} options
- * @param {string?} message
- */
 function exists(selector, options, message) {
   if (typeof selector !== 'string') {
     throw new TypeError(`Unexpected Parameter: ${selector}`)

diff --git a/lib/assertions/focused.js b/lib/assertions/focused.js
@@ -1,12 +1,6 @@
 const find = require('../helpers/find');
 const elementToString = require('../helpers/element-to-string');
 
-/**
- * Asserts that the passed in DOM element is currently focused.
- *
- * @param {HTMLElement|string} el
- * @param {string?} message
- */
 function focused(el, message) {
   let element = find.call(this, el);
   if (!element) return;

diff --git a/lib/assertions/missing.js b/lib/assertions/missing.js
@@ -1,11 +1,5 @@
 const exists = require('./exists');
 
-/**
- * Asserts that the passed in DOM element does not exist.
- *
- * @param {string} selector
- * @param {string?} message
- */
 function missing(selector, message) {
   return exists.call(this, selector, { count: 0 }, message);
 }

diff --git a/lib/assertions/not-focused.js b/lib/assertions/not-focused.js
@@ -1,12 +1,6 @@
 const find = require('../helpers/find');
 const elementToString = require('../helpers/element-to-string');
 
-/**
- * Asserts that the passed in DOM element is currently *not* focused.
- *
- * @param {HTMLElement|string} el
- * @param {string?} message
- */
 function notFocused(el, message) {
   let element = find.call(this, el);
   if (!element) return;

diff --git a/lib/assertions/text-contains.js b/lib/assertions/text-contains.js
@@ -1,14 +1,6 @@
 const find = require('../helpers/find');
 const elementToString = require('../helpers/element-to-string');
 
-/**
- * Asserts if `text` is contained in the `textContent` property
- * of the passed in DOM element.
- *
- * @param {HTMLElement|string} el
- * @param {string} text
- * @param {string?} message
- */
 function textContains(el, text, message) {
   let element = find.call(this, el);
   if (!element) return;

diff --git a/lib/assertions/text-matches.js b/lib/assertions/text-matches.js
@@ -1,14 +1,6 @@
 const find = require('../helpers/find');
 const elementToString = require('../helpers/element-to-string');
 
-/**
- * Asserts if `regex` is matching the `textContent` property
- * of the passed in DOM element.
- *
- * @param {HTMLElement|string} el
- * @param {RegExp} regex
- * @param {string?} message
- */
 function textContains(el, regex, message) {
   let element = find.call(this, el);
   if (!element) return;

diff --git a/package.json b/package.json
@@ -19,6 +19,7 @@
   "repository": "https://github.com/simplabs/qunit-dom",
   "scripts": {
     "build": "rollup -c",
+    "docs": "documentation readme lib/qunit-dom.js --readme-file=API.md --section=Assertions",
     "prepublish": "rollup -c",
     "test": "jest",
     "test:coverage": "jest --coverage",
@@ -30,6 +31,7 @@
     "broccoli-merge-trees": "^2.0.0"
   },
   "devDependencies": {
+    "documentation": "^5.3.2",
     "ember-cli": "~2.15.0-beta.2",
     "ember-cli-babel": "^6.6.0",
     "ember-cli-dependency-checker": "^2.0.0",