fix: generate jsdoc(umentation)

.eslintignore

@@ -1,3 +1,4 @@
 build/tasks/generate-imports.js
 !lib/core/imports/index.js
-lib/core/imports/*.js
+lib/core/imports/*.js
+doc/api/*

.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/**/*.* 
+.circleci/**/*.* 
+
+# ignore jsdoc api documentation generated files
+doc/api/*

.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"
+	}
+}

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'

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.

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) {

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",