From 9f9b15be23ebc330ff2feb8bd06b5964237d0feb Mon Sep 17 00:00:00 2001
From: Jey <jey.nandakumar@gmail.com>
Date: Mon, 30 Jul 2018 17:59:06 +0100
Subject: [PATCH] fix: generate jsdoc(umentation)

---
 .eslintignore                  |  3 ++-
 .gitignore                     |  5 ++++-
 .jsdoc.json                    | 16 ++++++++++++++++
 doc/API.md                     |  4 ++++
 doc/developer-guide.md         |  4 ++++
 lib/core/utils/get-selector.js |  7 +++----
 package.json                   |  5 ++++-
 7 files changed, 37 insertions(+), 7 deletions(-)
 create mode 100644 .jsdoc.json

diff --git a/.eslintignore b/.eslintignore
index f7b0f07008..9b55da3236 100644
--- a/.eslintignore
+++ b/.eslintignore
@@ -1,3 +1,4 @@
 build/tasks/generate-imports.js
 !lib/core/imports/index.js
-lib/core/imports/*.js
\ No newline at end of file
+lib/core/imports/*.js
+doc/api/*
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index a01f9832b6..84a78ff5bb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,4 +16,7 @@ lib/core/imports/*.js
 
 # running circleci locally to verify build, ignoring relevant files
 # if circle and docker is configured locally (copy circle.yml to .circleci/config.yml) - run -> circleci build
-.circleci/**/*.* 
\ No newline at end of file
+.circleci/**/*.* 
+
+# ignore jsdoc api documentation generated files
+doc/api/*
\ No newline at end of file
diff --git a/.jsdoc.json b/.jsdoc.json
new file mode 100644
index 0000000000..fb7a31d537
--- /dev/null
+++ b/.jsdoc.json
@@ -0,0 +1,16 @@
+{
+	"tags": {
+		"dictionaries": ["jsdoc"]
+	},
+	"source": {
+		"include": ["lib", "README.md"],
+		"includePattern": ".js$",
+		"excludePattern": "(node_modules/|doc/api)"
+	},
+	"opts": {
+		"destination": "./doc/api",
+		"encoding": "utf8",
+		"recurse": true,
+		"template": "./node_modules/minami"
+	}
+}
\ No newline at end of file
diff --git a/doc/API.md b/doc/API.md
index 93cd44053a..5e7f730b4a 100644
--- a/doc/API.md
+++ b/doc/API.md
@@ -55,6 +55,10 @@ The aXe API can be used as part of a broader process that is performed on many,
 
 The aXe APIs are provided in the javascript file axe.js. It must be included in the web page under test. Parameters are sent as javascript function parameters. Results are returned in JSON format.
 
+### Full API Reference for Developers
+
+For a full listing of API offered by aXe, clone the repository and run `npm run api-docs`. This generates `jsdoc` documentation under `doc/api` which can be viewed using the browser.
+
 ### API Notes
 
 * A Rule test is made up of sub-tests. Each sub-test is returned in an array of 'checks'
diff --git a/doc/developer-guide.md b/doc/developer-guide.md
index 2255939878..55dcee71fb 100644
--- a/doc/developer-guide.md
+++ b/doc/developer-guide.md
@@ -44,6 +44,10 @@ You can also load tests in any supported browser, which is helpful for debugging
 4. [Integration Tests](../test/integration/rules/)
 5. There are additional tests located in [test/integration/full/](../test/integration/full/) for tests that need to be run against their own document.
 
+### API Reference
+
+[See API exposed on aXe](./API.md#section-2-api-reference)
+
 ## Architecture Overview
 
 aXe tests for accessibility using objects called Rules. Each Rule tests for a high-level aspect of accessibility, such as color contrast, button labels, and alternate text for images. Each rule is made up of a series of Checks. Depending on the rule; all, some, or none of these checks must pass in order for the rule to pass.
diff --git a/lib/core/utils/get-selector.js b/lib/core/utils/get-selector.js
index c21adaeac9..f263c6ac15 100644
--- a/lib/core/utils/get-selector.js
+++ b/lib/core/utils/get-selector.js
@@ -212,9 +212,8 @@ function getElmId(elm) {
 
 /**
  * Return the base CSS selector for a given element
- *
  * @param	{HTMLElement} elm				 The element to get the selector for
- * @return {String | Array[String]}	Base CSS selector for the node
+ * @return {String|Array<String>}	Base CSS selector for the node
  */
 function getBaseSelector(elm) {
 	if (typeof isXHTML === 'undefined') {
@@ -376,9 +375,9 @@ function generateSelector(elm, options, doc) {
 
 /**
  * Gets a unique CSS selector
- * @param	{HTMLElement} node				 The element to get the selector for
+ * @param {HTMLElement} node The element to get the selector for
  * @param {Object} optional options
- * @return {String | Array[String]}	 Unique CSS selector for the node
+ * @returns {String|Array<String>} Unique CSS selector for the node
  */
 axe.utils.getSelector = function createUniqueSelector(elm, options = {}) {
 	if (!elm) {
diff --git a/package.json b/package.json
index 93fd0e6877..a5edd63717 100644
--- a/package.json
+++ b/package.json
@@ -55,8 +55,9 @@
     }
   },
   "scripts": {
+		"api-docs": "jsdoc --configure .jsdoc.json",
     "build": "grunt",
-		"test-dts": "tsc",
+    "test-dts": "tsc",
     "test": "npm run test-dts && grunt test",
     "test-fast": "grunt test-fast",
     "version": "echo \"use 'npm run release' to bump axe-core version\" && exit 1",
@@ -98,8 +99,10 @@
     "html-entities": "^1.2.0",
     "husky": "^0.14.3",
     "jquery": "^3.0.0",
+    "jsdoc": "^3.5.5",
     "lint-staged": "^7.2.0",
     "markdown-table": "^1.1.2",
+    "minami": "^1.2.3",
     "mocha": "^5.2.0",
     "prettier": "^1.13.6",
     "promise": "~8.0.1",