From bcd46bcaf216b44eb8e8dbdcd2bcf17db98f2bb9 Mon Sep 17 00:00:00 2001
From: Tony Kornmeier <akornmeier@users.noreply.github.com>
Date: Wed, 18 Oct 2017 10:40:56 -0400
Subject: [PATCH] docs: update jsdoc formatted comments for axe.common methods
 (#544)

* docs: update jsdoc formatted comments for axe.common methods, and a few in axe.core.utils

* docs: add additional context to axe.common methods, remove todo comments, add missing method desc

* fix: fix lint issues
---
 lib/commons/aria/attributes.js              | 14 +++++++-
 lib/commons/aria/index.js                   |  6 ++++
 lib/commons/aria/label-virtual.js           | 16 +++++++--
 lib/commons/aria/roles.js                   | 30 +++++++++++++++--
 lib/commons/color/contrast.js               | 29 ++++++++++++++---
 lib/commons/color/element-is-distinct.js    | 19 +++++++++--
 lib/commons/color/get-background-color.js   | 19 +++++++++--
 lib/commons/color/get-foreground-color.js   |  7 ++--
 lib/commons/color/incomplete-data.js        | 16 +++++++--
 lib/commons/color/index.js                  |  6 ++++
 lib/commons/dom/elements-below-floating.js  |  4 ++-
 lib/commons/dom/find-elms-in-context.js     | 18 ++++++-----
 lib/commons/dom/find-up.js                  |  8 +++--
 lib/commons/dom/get-composed-parent.js      | 11 ++++---
 lib/commons/dom/get-element-by-reference.js | 13 ++++++--
 lib/commons/dom/get-element-coordinates.js  | 33 ++++++++++---------
 lib/commons/dom/get-root-node.js            |  9 +++---
 lib/commons/dom/get-scroll-offset.js        |  9 ++++--
 lib/commons/dom/get-viewport-size.js        | 11 ++++---
 lib/commons/dom/has-content-virtual.js      | 36 +++++++++++++++------
 lib/commons/dom/idrefs.js                   |  7 ++--
 lib/commons/dom/index.js                    |  9 +++++-
 lib/commons/dom/is-focusable.js             |  7 ++--
 lib/commons/dom/is-html5.js                 | 13 ++++++--
 lib/commons/dom/is-in-text-block.js         |  8 +++--
 lib/commons/dom/is-node.js                  | 14 ++++++--
 lib/commons/dom/is-offscreen.js             | 10 +++++-
 lib/commons/dom/is-visible.js               | 12 +++++--
 lib/commons/dom/is-visual-content.js        | 13 +++++---
 lib/commons/dom/visually-contains.js        |  3 ++
 lib/commons/dom/visually-overlaps.js        |  3 ++
 lib/commons/index.js                        |  8 +++++
 lib/commons/table/get-all-cells.js          | 11 ++++++-
 lib/commons/table/get-cell-position.js      | 11 ++++---
 lib/commons/table/get-headers.js            |  9 ++++--
 lib/commons/table/get-scope.js              | 13 +++++---
 lib/commons/table/index.js                  |  9 +++++-
 lib/commons/table/is-column-header.js       | 13 +++++---
 lib/commons/table/is-data-cell.js           |  9 ++++--
 lib/commons/table/is-data-table.js          |  9 ++++--
 lib/commons/table/is-header.js              |  7 ++--
 lib/commons/table/is-row-header.js          | 13 +++++---
 lib/commons/table/to-grid.js                |  7 ++--
 lib/commons/table/traverse.js               | 15 +++++----
 lib/commons/text/accessible-text-virtual.js | 35 +++++++++++++-------
 lib/commons/text/index.js                   | 11 +++++--
 lib/commons/text/label-virtual.js           | 20 ++++++++++--
 lib/commons/text/sanitize.js                | 11 ++++++-
 lib/commons/text/visible-virtual.js         | 20 +++++++++++-
 lib/commons/utils/index.js                  | 12 +++++--
 lib/commons/utils/to-array.js               | 13 ++++++--
 lib/commons/utils/token-list.js             | 13 ++++++--
 lib/commons/utils/valid-langs.js            | 14 ++++++--
 lib/core/utils/contains.js                  |  5 ++-
 lib/core/utils/find-by.js                   |  5 ++-
 lib/core/utils/index.js                     |  9 +++++-
 lib/core/utils/is-hidden.js                 |  5 ++-
 lib/core/utils/qsa.js                       | 22 +++++++------
 58 files changed, 563 insertions(+), 179 deletions(-)

diff --git a/lib/commons/aria/attributes.js b/lib/commons/aria/attributes.js
index 22adffb053..d1824a8cf0 100644
--- a/lib/commons/aria/attributes.js
+++ b/lib/commons/aria/attributes.js
@@ -2,6 +2,9 @@
 
 /**
  * Get required attributes for a given role
+ * @method requiredAttr
+ * @memberof axe.commons.aria
+ * @instance
  * @param  {String} role The role to check
  * @return {Array}
  */
@@ -14,6 +17,9 @@ aria.requiredAttr = function (role) {
 
 /**
  * Get allowed attributes for a given role
+ * @method allowedAttr
+ * @memberof axe.commons.aria
+ * @instance
  * @param  {String} role The role to check
  * @return {Array}
  */
@@ -28,6 +34,9 @@ aria.allowedAttr = function (role) {
 
 /**
  * Check if an aria- attribute name is valid
+ * @method validateAttr
+ * @memberof axe.commons.aria
+ * @instance
  * @param  {String} att The attribute name
  * @return {Boolean}
  */
@@ -38,6 +47,9 @@ aria.validateAttr = function (att) {
 
 /**
  * Validate the value of an ARIA attribute
+ * @method validateAttrValue
+ * @memberof axe.commons.aria
+ * @instance
  * @param  {HTMLElement} node The element to check
  * @param  {String} attr The name of the attribute
  * @return {Boolean}
@@ -60,7 +72,7 @@ aria.validateAttrValue = function (node, attr) {
 	case 'nmtoken':
 		return (typeof value === 'string' && attrInfo.values.indexOf(value.toLowerCase()) !== -1);
 
-	case 'nmtokens': 
+	case 'nmtokens':
 		list = axe.utils.tokenList(value);
 		// Check if any value isn't in the list of values
 		return list.reduce(function (result, token) {
diff --git a/lib/commons/aria/index.js b/lib/commons/aria/index.js
index c93c95cd51..7bba8233c6 100644
--- a/lib/commons/aria/index.js
+++ b/lib/commons/aria/index.js
@@ -1,3 +1,9 @@
+/**
+ * Namespace for aria-related utilities.
+ * @namespace commons.aria
+ * @memberof axe
+ */
+
 var aria = commons.aria = {},
 	lookupTables = aria._lut = {};
 
diff --git a/lib/commons/aria/label-virtual.js b/lib/commons/aria/label-virtual.js
index 88b479db4c..aca450a5f1 100644
--- a/lib/commons/aria/label-virtual.js
+++ b/lib/commons/aria/label-virtual.js
@@ -1,8 +1,12 @@
-/*global axe, aria, dom, text */
+/* global axe, aria, dom, text */
+
 /**
  * Gets the accessible ARIA label text of a given element
  * @see http://www.w3.org/WAI/PF/aria/roles#namecalculation
- * @param  {Object} The virtualNode to test
+ * @method labelVirtual
+ * @memberof axe.commons.aria
+ * @instance
+ * @param  {Object} actualNode The virtualNode to test
  * @return {Mixed}  String of visible text, or `null` if no label is found
  */
 aria.labelVirtual = function ({ actualNode }) {
@@ -33,6 +37,14 @@ aria.labelVirtual = function ({ actualNode }) {
 	return null;
 };
 
+/**
+ * Gets the aria label for a given node
+ * @method label
+ * @memberof axe.commons.aria
+ * @instance
+ * @param  {HTMLElement} node The element to check
+ * @return {Mixed} String of visible text, or `null` if no label is found
+ */
 aria.label = function (node) {
 	node = axe.utils.getNodeFromTree(axe._tree[0], node);
 	return aria.labelVirtual(node);
diff --git a/lib/commons/aria/roles.js b/lib/commons/aria/roles.js
index bd822e1667..56bd52b4b8 100644
--- a/lib/commons/aria/roles.js
+++ b/lib/commons/aria/roles.js
@@ -1,7 +1,10 @@
-/*global aria, lookupTables, axe */
+/* global aria, lookupTables, axe */
 
 /**
  * Check if a given role is valid
+ * @method isValidRole
+ * @memberof axe.commons.aria
+ * @instance
  * @param  {String}  role The role to check
  * @return {Boolean}
  */
@@ -15,8 +18,11 @@ aria.isValidRole = function (role) {
 };
 
 /**
- * Get the roles that get name from contents
- * @return {Array}           Array of roles that match the type
+ * Get the roles that get name from the element's contents
+ * @method getRolesWithNameFromContents
+ * @memberof axe.commons.aria
+ * @instance
+ * @return {Array} Array of roles that match the type
  */
 aria.getRolesWithNameFromContents = function () {
 	return Object.keys(lookupTables.role).filter(function (r) {
@@ -27,6 +33,9 @@ aria.getRolesWithNameFromContents = function () {
 
 /**
  * Get the roles that have a certain "type"
+ * @method getRolesByType
+ * @memberof axe.commons.aria
+ * @instance
  * @param  {String} roleType The roletype to check
  * @return {Array}           Array of roles that match the type
  */
@@ -38,6 +47,9 @@ aria.getRolesByType = function (roleType) {
 
 /**
  * Get the "type" of role; either widget, composite, abstract, landmark or `null`
+ * @method getRoleType
+ * @memberof axe.commons.aria
+ * @instance
  * @param  {String} role The role to check
  * @return {Mixed}       String if a matching role and its type are found, otherwise `null`
  */
@@ -49,6 +61,9 @@ aria.getRoleType = function (role) {
 
 /**
  * Get the required owned (children) roles for a given role
+ * @method requiredOwned
+ * @memberof axe.commons.aria
+ * @instance
  * @param  {String} role The role to check
  * @return {Mixed}       Either an Array of required owned elements or `null` if there are none
  */
@@ -65,6 +80,9 @@ aria.requiredOwned = function (role) {
 
 /**
  * Get the required context (parent) roles for a given role
+ * @method requiredContext
+ * @memberof axe.commons.aria
+ * @instance
  * @param  {String} role The role to check
  * @return {Mixed}       Either an Array of required context elements or `null` if there are none
  */
@@ -81,6 +99,9 @@ aria.requiredContext = function (role) {
 
 /**
  * Get a list of CSS selectors of nodes that have an implicit role
+ * @method implicitNodes
+ * @memberof axe.commons.aria
+ * @instance
  * @param  {String} role The role to check
  * @return {Mixed}       Either an Array of CSS selectors or `null` if there are none
  */
@@ -98,6 +119,9 @@ aria.implicitNodes = function (role) {
 
 /**
  * Get the implicit role for a given node
+ * @method implicitRole
+ * @memberof axe.commons.aria
+ * @instance
  * @param  {HTMLElement} node The node to test
  * @return {Mixed}      Either the role or `null` if there is none
  */
diff --git a/lib/commons/color/contrast.js b/lib/commons/color/contrast.js
index b2162c7f02..4717fc4a32 100644
--- a/lib/commons/color/contrast.js
+++ b/lib/commons/color/contrast.js
@@ -1,7 +1,8 @@
-/*global color */
+/* global color */
 
 /**
- * @constructor
+ * @class Color
+ * @memberof axe.commons.color
  * @param {number} red
  * @param {number} green
  * @param {number} blue
@@ -22,6 +23,9 @@ color.Color = function (red, green, blue, alpha) {
 
 	/**
 	 * Provide the hex string value for the color
+	 * @method toHexString
+	 * @memberof axe.commons.color.Color
+	 * @instance
 	 * @return {string}
 	 */
 	this.toHexString = function () {
@@ -38,6 +42,9 @@ color.Color = function (red, green, blue, alpha) {
 
 	/**
 	 * Set the color value based on a CSS RGB/RGBA string
+	 * @method parseRgbString
+	 * @memberof axe.commons.color.Color
+	 * @instance
 	 * @param  {string}  rgb  The string value
 	 */
 	this.parseRgbString = function (colorString) {
@@ -72,6 +79,9 @@ color.Color = function (red, green, blue, alpha) {
 	/**
 	 * Get the relative luminance value
 	 * using algorithm from http://www.w3.org/WAI/GL/wiki/Relative_luminance
+	 * @method getRelativeLuminance
+	 * @memberof axe.commons.color.Color
+	 * @instance
 	 * @return {number} The luminance value, ranges from 0 to 1
 	 */
 	this.getRelativeLuminance = function () {
@@ -89,9 +99,12 @@ color.Color = function (red, green, blue, alpha) {
 
 /**
  * Combine the two given color according to alpha blending.
- * @param {Color} fgColor
- * @param {Color} bgColor
- * @return {Color}
+ * @method flattenColors
+ * @memberof axe.commons.color.Color
+ * @instance
+ * @param {Color} fgColor Foreground color
+ * @param {Color} bgColor Background color
+ * @return {Color} Blended color
  */
 color.flattenColors = function (fgColor, bgColor) {
 	var alpha = fgColor.alpha;
@@ -105,6 +118,9 @@ color.flattenColors = function (fgColor, bgColor) {
 
 /**
  * Get the contrast of two colors
+ * @method getContrast
+ * @memberof axe.commons.color.Color
+ * @instance
  * @param  {Color}  bgcolor  Background color
  * @param  {Color}  fgcolor  Foreground color
  * @return {number} The contrast ratio
@@ -124,6 +140,9 @@ color.getContrast = function (bgColor, fgColor) {
 
 /**
  * Check whether certain text properties meet WCAG contrast rules
+ * @method hasValidContrastRatio
+ * @memberof axe.commons.color.Color
+ * @instance
  * @param  {Color}  bgcolor  Background color
  * @param  {Color}  fgcolor  Foreground color
  * @param  {number}  fontSize  Font size of text, in pixels
diff --git a/lib/commons/color/element-is-distinct.js b/lib/commons/color/element-is-distinct.js
index 343960bd32..544b11542c 100644
--- a/lib/commons/color/element-is-distinct.js
+++ b/lib/commons/color/element-is-distinct.js
@@ -1,5 +1,11 @@
-/*global color */
+/* global color */
 
+/**
+ * Creates a string array of fonts for given CSSStyleDeclaration object
+ * @private
+ * @param {Object} style CSSStyleDeclaration object
+ * @return {Array}
+ */
 function _getFonts(style) {
 	return style.getPropertyValue('font-family')
 	.split(/[,;]/g)
@@ -8,6 +14,15 @@ function _getFonts(style) {
 	});
 }
 
+/**
+ * Determine if the text content of two nodes is styled in a way that they can be distinguished without relying on color
+ * @method elementIsDistinct
+ * @memberof axe.commons.color
+ * @instance
+ * @param  {HTMLElement} node The element to check
+ * @param  {HTMLElement} ancestorNode The ancestor node element to check
+ * @return {Boolean}
+ */
 function elementIsDistinct(node, ancestorNode) {
 	var nodeStyle = window.getComputedStyle(node);
 
@@ -57,4 +72,4 @@ function elementIsDistinct(node, ancestorNode) {
 }
 
 
-color.elementIsDistinct = elementIsDistinct;
\ No newline at end of file
+color.elementIsDistinct = elementIsDistinct;
diff --git a/lib/commons/color/get-background-color.js b/lib/commons/color/get-background-color.js
index a64a95a0fc..f439ebb634 100644
--- a/lib/commons/color/get-background-color.js
+++ b/lib/commons/color/get-background-color.js
@@ -138,7 +138,7 @@ function includeMissingElements(elmStack, elm) {
 						// found an ancestor not in elmStack, and it overlaps
 						let overlaps = axe.commons.dom.visuallyOverlaps(elm.getBoundingClientRect(), ancestorMatch);
 						if (overlaps) {
-							// if target is in the elementMap, use its position. 
+							// if target is in the elementMap, use its position.
 							bgNodes.splice(tagArray.indexOf(candidate) + 1, 0, ancestorMatch);
 						}
 					}
@@ -180,8 +180,12 @@ function sortPageBackground(elmStack) {
 }
 
 /**
- * Get all elements rendered underneath the current element,
- * in the order in which it is rendered
+ * Get all elements rendered underneath the current element, In the order they are displayed (front to back)
+ * @method getBackgroundStack
+ * @memberof axe.commons.color
+ * @instance
+ * @param {Element} elm
+ * @return {Array}
  */
 color.getBackgroundStack = function(elm) {
 	let rect = elm.getBoundingClientRect();
@@ -214,6 +218,15 @@ color.getBackgroundStack = function(elm) {
 	return elmIndex !== -1 ? elmStack : null;
 };
 
+/**
+ * Returns background color for element
+ * Uses color.getBackgroundStack() to get all elements rendered underneath the current element to
+ * help determine the background color.
+ * @param  {Element} elm Element to determine background color
+ * @param  {Array}   [bgElms=[]]      [description]
+ * @param  {Boolean} [noScroll=false] [description]
+ * @return {Color}                   [description]
+ */
 color.getBackgroundColor = function(elm, bgElms = [], noScroll = false) {
 	if(noScroll !== true) {
 		// Avoid scrolling overflow:hidden containers, by only aligning to top
diff --git a/lib/commons/color/get-foreground-color.js b/lib/commons/color/get-foreground-color.js
index f001fe3f5e..427880ae65 100644
--- a/lib/commons/color/get-foreground-color.js
+++ b/lib/commons/color/get-foreground-color.js
@@ -1,11 +1,14 @@
-/*global axe, color */
+/* global axe, color */
 
 /**
  * Returns the flattened foreground color of an element, or null if it can't be determined because
  * of transparency
+ * @method getForegroundColor
+ * @memberof axe.commons.color
+ * @instance
  * @param {Element} node
  * @param {Boolean} noScroll (default false)
- * @return {Color}
+ * @return {Color|null}
  */
 color.getForegroundColor = function (node, noScroll) {
 	var nodeStyle = window.getComputedStyle(node);
diff --git a/lib/commons/color/incomplete-data.js b/lib/commons/color/incomplete-data.js
index 288f61457d..671457bb08 100644
--- a/lib/commons/color/incomplete-data.js
+++ b/lib/commons/color/incomplete-data.js
@@ -2,14 +2,20 @@
 
 /**
  * API for handling incomplete color data
+ * @namespace axe.commons.color.incompleteData
+ * @inner
  */
+
 color.incompleteData = (function() {
 	var data = {};
 	return {
 		/**
 		 * Store incomplete data by key with a string value
-		 * @param {String} key 						Identifier for missing data point (fgColor, bgColor, etc.)
-		 * @param {String} reason 				Missing data reason to match message template
+		 * @method set
+		 * @memberof axe.commons.color.incompleteData
+		 * @instance
+		 * @param {String} key Identifier for missing data point (fgColor, bgColor, etc.)
+		 * @param {String} reason Missing data reason to match message template
 		 */
 		set: function(key, reason) {
 			if (typeof key !== 'string') {
@@ -22,6 +28,9 @@ color.incompleteData = (function() {
 		},
 		/**
 		 * Get incomplete data by key
+		 * @method get
+		 * @memberof axe.commons.color.incompleteData
+		 * @instance
 		 * @param {String} key 	Identifier for missing data point (fgColor, bgColor, etc.)
 		 * @return {String} String for reason we couldn't tell
 		 */
@@ -30,6 +39,9 @@ color.incompleteData = (function() {
 		},
 		/**
 		 * Clear incomplete data on demand
+		 * @method clear
+		 * @memberof axe.commons.color.incompleteData
+		 * @instance
 		 */
 		clear: function() {
 			data = {};
diff --git a/lib/commons/color/index.js b/lib/commons/color/index.js
index b53233e96c..5b62fcb916 100644
--- a/lib/commons/color/index.js
+++ b/lib/commons/color/index.js
@@ -1,2 +1,8 @@
+/**
+ * Namespace for color-related utilities.
+ * @namespace commons.color
+ * @memberof axe
+ */
+
 var color = {};
 commons.color = color;
diff --git a/lib/commons/dom/elements-below-floating.js b/lib/commons/dom/elements-below-floating.js
index 8a20481504..8368b51224 100644
--- a/lib/commons/dom/elements-below-floating.js
+++ b/lib/commons/dom/elements-below-floating.js
@@ -2,7 +2,9 @@
 
 /**
  * Reduce an array of elements to only those that are below a 'floating' element.
- *
+ * @method reduceToElementsBelowFloating
+ * @memberof axe.commons.dom
+ * @instance
  * @param {Array} elements
  * @param {Element} targetNode
  * @returns {Array}
diff --git a/lib/commons/dom/find-elms-in-context.js b/lib/commons/dom/find-elms-in-context.js
index 4e27b99d79..0c5333a323 100644
--- a/lib/commons/dom/find-elms-in-context.js
+++ b/lib/commons/dom/find-elms-in-context.js
@@ -1,14 +1,16 @@
 /* global axe, dom */
+
 /**
  * Find elements referenced from a given context
- * 
- * @param object {
- *    context:  Node    Element in the same context
- *    value:    String  attribute value to search for
- *    attr:     String  attribute name to search for
- *    elm:      String  ndoeName to search for (optional)
- *  }
- * @return Array[Node]  
+ * @method findElmsInContext
+ * @memberof axe.commons.dom
+ * @instance
+ * @param {Object} element
+ * @param {String} element.context Element in the same context
+ * @param {String} element.value Attribute value to search for
+ * @param {String} element.attr Attribute name to search for
+ * @param {String} element.elm NodeName to search for (optional)
+ * @return {Array<Node>}
  */
 dom.findElmsInContext = function ({ context, value, attr, elm = '' }) {
   let root;
diff --git a/lib/commons/dom/find-up.js b/lib/commons/dom/find-up.js
index 8f2db7f8f9..589c899dd7 100644
--- a/lib/commons/dom/find-up.js
+++ b/lib/commons/dom/find-up.js
@@ -1,11 +1,13 @@
-/*global dom, axe */
+/* global dom, axe */
 /**
  * recusively walk up the DOM, checking for a node which matches a selector
  *
  * **WARNING:** this should be used sparingly, as it's not even close to being performant
- *
+ * @method findUp
+ * @memberof axe.commons.dom
+ * @instance
  * @param {HTMLElement|String} element The starting HTMLElement
- * @param {String} selector The selector for the HTMLElement
+ * @param {String} target The selector for the HTMLElement
  * @return {HTMLElement|null} Either the matching HTMLElement or `null` if there was no match
  */
 dom.findUp = function (element, target) {
diff --git a/lib/commons/dom/get-composed-parent.js b/lib/commons/dom/get-composed-parent.js
index 82e50dac78..1d26b63e85 100644
--- a/lib/commons/dom/get-composed-parent.js
+++ b/lib/commons/dom/get-composed-parent.js
@@ -1,8 +1,11 @@
-/*global dom */
+/* global dom */
 /**
- * Get an element's parent in the composed tree
- * @param   DOMNode   Element
- * @return  DOMNode   Parent element
+ * Get an element's parent in the flattened tree
+ * @method getComposedParent
+ * @memberof axe.commons.dom
+ * @instance
+ * @param {Node} element
+ * @return {Node|null} Parent element or Null for root node
  */
 dom.getComposedParent = function getComposedParent (element)  {
   if (element.assignedSlot) {
diff --git a/lib/commons/dom/get-element-by-reference.js b/lib/commons/dom/get-element-by-reference.js
index aa24d35ca1..fb1a552718 100644
--- a/lib/commons/dom/get-element-by-reference.js
+++ b/lib/commons/dom/get-element-by-reference.js
@@ -1,5 +1,14 @@
-/*global dom */
+/* global dom */
 
+/**
+ * Returns a reference to the element matching the attr URL fragment value
+ * @method getElementByReference
+ * @memberof axe.commons.dom
+ * @instance
+ * @param {Element} node
+ * @param {String} attr Attribute name (href)
+ * @return {Element}
+ */
 dom.getElementByReference = function (node, attr) {
 	let fragment = node.getAttribute(attr);
 
@@ -17,4 +26,4 @@ dom.getElementByReference = function (node, attr) {
 		}
 	}
 	return null;
-};
\ No newline at end of file
+};
diff --git a/lib/commons/dom/get-element-coordinates.js b/lib/commons/dom/get-element-coordinates.js
index 35f8045b69..38a125b1cb 100644
--- a/lib/commons/dom/get-element-coordinates.js
+++ b/lib/commons/dom/get-element-coordinates.js
@@ -1,22 +1,24 @@
-/*global dom */
+/* global dom */
+
 /**
  * Get the coordinates of the element passed into the function relative to the document
- *
- * #### Returns
- *
- * Returns a `Object` with the following properties, which
+ * @method getElementCoordinates
+ * @memberof axe.commons.dom
+ * @instance
+ * @param {HTMLElement} element The HTMLElement
+ * @return {elementObj} elementObj Returns a `Object` with the following properties, which
  * each hold a value representing the pixels for each of the
- * respective coordinates:
- *
- * - `top`
- * - `right`
- * - `bottom`
- * - `left`
- * - `width`
- * - `height`
- *
- * @param {HTMLElement} el The HTMLElement
  */
+ /**
+  * @typedef elementObj
+  * @type {Object}
+  * @property {Number} top The top coordinate of the element
+  * @property {Number} right The right coordinate of the element
+  * @property {Number} bottom The bottom coordinate of the element
+  * @property {Number} left The left coordinate of the element
+  * @property {Number} width The width of the element
+  * @property {Number} height The height of the element
+  */
 dom.getElementCoordinates = function (element) {
 	'use strict';
 
@@ -30,7 +32,6 @@ dom.getElementCoordinates = function (element) {
 		right: coords.right + xOffset,
 		bottom: coords.bottom + yOffset,
 		left: coords.left + xOffset,
-
 		width: coords.right - coords.left,
 		height: coords.bottom - coords.top
 	};
diff --git a/lib/commons/dom/get-root-node.js b/lib/commons/dom/get-root-node.js
index fb7fbffd54..f88568019e 100644
--- a/lib/commons/dom/get-root-node.js
+++ b/lib/commons/dom/get-root-node.js
@@ -2,16 +2,17 @@
 
 /**
  * Return the document or document fragment (shadow DOM)
- *
+ * @method getRootNode
+ * @memberof axe.commons.dom
+ * @instance
  * @param {Element} node
  * @returns {DocumentFragment|Document}
  */
-
 dom.getRootNode = function (node) {
 	var doc = (node.getRootNode && node.getRootNode()) || document; // this is for backwards compatibility
 	if (doc === node) {
 		// disconnected node
 		doc = document;
 	}
-	return doc;	
-};
\ No newline at end of file
+	return doc;
+};
diff --git a/lib/commons/dom/get-scroll-offset.js b/lib/commons/dom/get-scroll-offset.js
index 1b920e41b2..ecf53d9cfb 100644
--- a/lib/commons/dom/get-scroll-offset.js
+++ b/lib/commons/dom/get-scroll-offset.js
@@ -1,7 +1,10 @@
-/*global dom */
+/* global dom */
+
 /**
  * Get the scroll offset of the document passed in
- *
+ * @method getScrollOffset
+ * @memberof axe.commons.dom
+ * @instance
  * @param {Document} element The element to evaluate, defaults to document
  * @return {Object} Contains the attributes `x` and `y` which contain the scroll offsets
  */
@@ -27,4 +30,4 @@ dom.getScrollOffset = function (element) {
 		left: element.scrollLeft,
 		top: element.scrollTop
 	};
-};
\ No newline at end of file
+};
diff --git a/lib/commons/dom/get-viewport-size.js b/lib/commons/dom/get-viewport-size.js
index 0fd2fe9b10..dd310ee79a 100644
--- a/lib/commons/dom/get-viewport-size.js
+++ b/lib/commons/dom/get-viewport-size.js
@@ -1,9 +1,10 @@
-/*global dom */
+/* global dom */
 /**
  * Gets the width and height of the viewport; used to calculate the right and bottom boundaries of the viewable area.
- *
- * @api private
- * @param  {Object}  window The `window` object that should be measured
+ * @method getViewportSize
+ * @memberof axe.commons.dom
+ * @instance
+ * @param  {Object}  win The `window` object that should be measured
  * @return {Object}  Object with the `width` and `height` of the viewport
  */
 dom.getViewportSize = function (win) {
@@ -34,4 +35,4 @@ dom.getViewportSize = function (win) {
 		width: body.clientWidth,
 		height: body.clientHeight
 	};
-};
\ No newline at end of file
+};
diff --git a/lib/commons/dom/has-content-virtual.js b/lib/commons/dom/has-content-virtual.js
index 1674aa710d..b01854b72c 100644
--- a/lib/commons/dom/has-content-virtual.js
+++ b/lib/commons/dom/has-content-virtual.js
@@ -1,4 +1,4 @@
-/*global dom, aria, axe */
+/* global dom, aria, axe */
 const hiddenTextElms = [
   'HEAD', 'TITLE', 'TEMPLATE', 'SCRIPT','STYLE',
   'IFRAME', 'OBJECT', 'VIDEO', 'AUDIO', 'NOSCRIPT'
@@ -13,11 +13,14 @@ function hasChildTextNodes (elm) {
 }
 
 /**
- * Check that the element has visible content
- * in the form of either text, an aria-label or visual content such as image
- *
- * @param {Object} virtual DOM node
- * @return boolean
+ * Check that the element has visible content in the form of either text,
+ * an aria-label or visual content such as image
+ * @method hasContentVirtual
+ * @memberof axe.commons.dom
+ * @instance
+ * @param  {VirtualNode} elm Virtual Node to search
+ * @param  {Boolean} noRecursion If true, only the element is checked, otherwise it will search all child nodes
+ * @return {Boolean}
  */
 dom.hasContentVirtual = function (elm, noRecursion) {
   return (
@@ -35,13 +38,26 @@ dom.hasContentVirtual = function (elm, noRecursion) {
 };
 
 /**
- * Like hasContentVirtual, except with a DOM Node
+ * Find virtual node and call hasContentVirtual()
  * IMPORTANT: This method requires the composed tree at axe._tree
- *
- * @param {Object}  DOM node
- * @return boolean
+ * @see axe.commons.dom.hasContentVirtual
+ * @method hasContent
+ * @memberof axe.commons.dom
+ * @instance
+ * @param {DOMNode} elm DOMNode element to check
+ * @param  {Boolean} noRecursion If true, only the element is checked, otherwise it will search all child nodes
+ * @return {Boolean}
  */
 dom.hasContent = function hasContent (elm, noRecursion) {
   elm = axe.utils.getNodeFromTree(axe._tree[0], elm);
   return dom.hasContentVirtual(elm, noRecursion);
 };
+
+/**
+ * @typedef VirtualNode
+ * @type {Object}
+ * @property {HTMLElement} actualNode reference to actual HTML DOM element
+ * @property {Array<VirtualNode>} children array of child virtualNodes
+ * @property {String} shadowId The shadowId indicates whether the node is in a shadow root
+ * and if it is, which one it is inside the boundary.
+ */
diff --git a/lib/commons/dom/idrefs.js b/lib/commons/dom/idrefs.js
index 7b000df9cf..203e073411 100644
--- a/lib/commons/dom/idrefs.js
+++ b/lib/commons/dom/idrefs.js
@@ -3,9 +3,12 @@
 /**
  * Get elements referenced via a space-separated token attribute;
  * it will insert `null` for any Element that is not found
+ * @method idrefs
+ * @memberof axe.commons.dom
+ * @instance
  * @param  {HTMLElement} node
  * @param  {String} attr The name of attribute
- * @return {Array}      Array of elements (or `null` if not found)
+ * @return {Array|null} Array of elements (or `null` if not found)
  *
  * NOTE: When in a shadow DOM environment: ID refs (even for slotted content)
  * refer to the document in which the element is considered to be in the
@@ -29,4 +32,4 @@ dom.idrefs = function (node, attr) {
 	}
 
 	return result;
-};
\ No newline at end of file
+};
diff --git a/lib/commons/dom/index.js b/lib/commons/dom/index.js
index d83331fe53..e3bda7cf4e 100644
--- a/lib/commons/dom/index.js
+++ b/lib/commons/dom/index.js
@@ -1,2 +1,9 @@
-/*exported dom */
+/* exported dom */
+
+/**
+ * Namespace for dom-related utilities.
+ * @namespace dom
+ * @memberof axe.commons
+ */
+
 var dom = commons.dom = {};
diff --git a/lib/commons/dom/is-focusable.js b/lib/commons/dom/is-focusable.js
index ba3abce134..5735cbe877 100644
--- a/lib/commons/dom/is-focusable.js
+++ b/lib/commons/dom/is-focusable.js
@@ -1,8 +1,11 @@
-/*global dom */
+/* global dom */
 /* jshint maxcomplexity: 20 */
 /**
  * Determines if an element is focusable
- * @param {HTMLelement} element The HTMLelement
+ * @method isFocusable
+ * @memberof axe.commons.dom
+ * @instance
+ * @param {HTMLElement} el The HTMLElement
  * @return {Boolean} The element's focusability status
  */
 
diff --git a/lib/commons/dom/is-html5.js b/lib/commons/dom/is-html5.js
index 52e8bcee34..d9fabfa64d 100644
--- a/lib/commons/dom/is-html5.js
+++ b/lib/commons/dom/is-html5.js
@@ -1,8 +1,17 @@
-/*global dom */
+/* global dom */
+
+/**
+ * Determines if a document node is HTML 5
+ * @method isHTML5
+ * @memberof axe.commons.dom
+ * @instance
+ * @param {Node} doc
+ * @return {Boolean}
+ */
 dom.isHTML5 = function (doc) {
 	var node = doc.doctype;
 	if (node === null) {
 		return false;
 	}
 	return node.name === 'html' && !node.publicId && !node.systemId;
-};
\ No newline at end of file
+};
diff --git a/lib/commons/dom/is-in-text-block.js b/lib/commons/dom/is-in-text-block.js
index a6f867b508..4873d18526 100644
--- a/lib/commons/dom/is-in-text-block.js
+++ b/lib/commons/dom/is-in-text-block.js
@@ -20,7 +20,11 @@ function getBlockParent (node) {
 	return axe.utils.getNodeFromTree(axe._tree[0], parentBlock);
 }
 
-
+/**
+ * Determines if an element is within a text block
+ * @param  {Element} node [description]
+ * @return {Boolean}      [description]
+ */
 dom.isInTextBlock = function isInTextBlock(node) {
 	// jshint maxcomplexity: 15
 	if (isBlock(node)) {
@@ -34,7 +38,7 @@ dom.isInTextBlock = function isInTextBlock(node) {
 	let linkText = '';
 	let inBrBlock = 0;
 
-	// We want to ignore hidden text, and if br / hr is used, only use the section of the parent 
+	// We want to ignore hidden text, and if br / hr is used, only use the section of the parent
 	// that has the link we're looking at
 	walkDomNode(virtualParent, function (currNode) {
 		// We're already passed it, skip everything else
diff --git a/lib/commons/dom/is-node.js b/lib/commons/dom/is-node.js
index bacd8f914d..5207a38196 100644
--- a/lib/commons/dom/is-node.js
+++ b/lib/commons/dom/is-node.js
@@ -1,5 +1,13 @@
-/*global dom */
-dom.isNode = function (candidate) {
+/* global dom */
+/**
+ * Determines if element is an instance of Node
+ * @method isNode
+ * @memberof axe.commons.dom
+ * @instance
+ * @param  {Element} element
+ * @return {Boolean}
+ */
+dom.isNode = function (element) {
 	'use strict';
-	return candidate instanceof Node;
+	return element instanceof Node;
 };
diff --git a/lib/commons/dom/is-offscreen.js b/lib/commons/dom/is-offscreen.js
index 1c960abb48..0b0d406f19 100644
--- a/lib/commons/dom/is-offscreen.js
+++ b/lib/commons/dom/is-offscreen.js
@@ -1,4 +1,4 @@
-/*global dom */
+/* global dom */
 
 function noParentScrolled (element, offset) {
 	element = dom.getComposedParent(element);
@@ -14,6 +14,14 @@ function noParentScrolled (element, offset) {
 	return true;
 }
 
+/**
+ * Determines if element is off screen
+ * @method isOffscreen
+ * @memberof axe.commons.dom
+ * @instance
+ * @param  {Element} element
+ * @return {Boolean}
+ */
 dom.isOffscreen = function (element) {
 	let leftBoundary;
 	const docElement = document.documentElement;
diff --git a/lib/commons/dom/is-visible.js b/lib/commons/dom/is-visible.js
index 6318e2b8e8..7016582b1c 100644
--- a/lib/commons/dom/is-visible.js
+++ b/lib/commons/dom/is-visible.js
@@ -1,8 +1,11 @@
-/*global dom */
-/*jshint maxcomplexity: 11 */
+/* global dom */
+/* jshint maxcomplexity: 11 */
 
 /**
  * Determines if an element is hidden with the clip rect technique
+ * @method isClipped
+ * @memberof axe.commons.dom
+ * @private
  * @param  {String}  clip Computed property value of clip
  * @return {Boolean}
  */
@@ -20,9 +23,12 @@ function isClipped(clip) {
 
 /**
  * Determine whether an element is visible
- *
+ * @method isVisible
+ * @memberof axe.commons.dom
+ * @instance
  * @param {HTMLElement} el The HTMLElement
  * @param {Boolean} screenReader When provided, will evaluate visibility from the perspective of a screen reader
+ * @param {Boolean} recursed
  * @return {Boolean} The element's visibilty status
  */
 dom.isVisible = function (el, screenReader, recursed) {
diff --git a/lib/commons/dom/is-visual-content.js b/lib/commons/dom/is-visual-content.js
index 133dfacfad..c7e99dfaed 100644
--- a/lib/commons/dom/is-visual-content.js
+++ b/lib/commons/dom/is-visual-content.js
@@ -8,16 +8,19 @@ const visualRoles = [
 
 /**
  * Check if an element is an inherently visual element
- * @param  {object}  candidate The node to check
+ * @method isVisualContent
+ * @memberof axe.commons.dom
+ * @instance
+ * @param  {Element} element The element to check
  * @return {Boolean}
  */
-dom.isVisualContent = function (candidate) {
-	const role = candidate.getAttribute('role');
+dom.isVisualContent = function (element) {
+	const role = element.getAttribute('role');
 	if (role) {
 		return (visualRoles.indexOf(role) !== -1);
 	}
 
-	switch (candidate.tagName.toUpperCase()) {
+	switch (element.tagName.toUpperCase()) {
 		case 'IMG':
 		case 'IFRAME':
 		case 'OBJECT':
@@ -34,7 +37,7 @@ dom.isVisualContent = function (candidate) {
 		case 'METER':
 			return true;
 		case 'INPUT':
-			return candidate.type !== 'hidden';
+			return element.type !== 'hidden';
 		default:
 			return false;
 	}
diff --git a/lib/commons/dom/visually-contains.js b/lib/commons/dom/visually-contains.js
index 158892e691..d70216e4a5 100644
--- a/lib/commons/dom/visually-contains.js
+++ b/lib/commons/dom/visually-contains.js
@@ -4,6 +4,9 @@
 /**
  * Checks whether a parent element visually contains its child, either directly or via scrolling.
  * Assumes that |parent| is an ancestor of |node|.
+ * @method visuallyContains
+ * @memberof axe.commons.dom
+ * @instance
  * @param {Element} node
  * @param {Element} parent
  * @return {boolean} True if node is visually contained within parent
diff --git a/lib/commons/dom/visually-overlaps.js b/lib/commons/dom/visually-overlaps.js
index 9b2f4d1388..87c035b5ad 100644
--- a/lib/commons/dom/visually-overlaps.js
+++ b/lib/commons/dom/visually-overlaps.js
@@ -3,6 +3,9 @@
 
 /**
  * Checks whether a parent element visually overlaps a rectangle, either directly or via scrolling.
+ * @method visuallyOverlaps
+ * @memberof axe.commons.dom
+ * @instance
  * @param {DOMRect} rect
  * @param {Element} parent
  * @return {boolean} True if rect is visually contained within parent
diff --git a/lib/commons/index.js b/lib/commons/index.js
index 972e62e9ad..0c99f643fc 100644
--- a/lib/commons/index.js
+++ b/lib/commons/index.js
@@ -1,2 +1,10 @@
 /*exported commons */
+/** @namespace axe */
+
+/**
+ * Namespace for axe common methods.
+ * @namespace commons
+ * @memberof axe
+ */
+
 var commons = {};
diff --git a/lib/commons/table/get-all-cells.js b/lib/commons/table/get-all-cells.js
index 267c2798b8..6ecc292bdd 100644
--- a/lib/commons/table/get-all-cells.js
+++ b/lib/commons/table/get-all-cells.js
@@ -1,4 +1,13 @@
 /* global table */
+
+/**
+ * Returns all cells contained in given HTMLTableElement
+ * @method getAllCells
+ * @memberof axe.commons.table
+ * @instance
+ * @param  {HTMLTableElement} tableElm Table Element to get cells from
+ * @return {Array<HTMLTableCellElement>}
+ */
 table.getAllCells = function (tableElm) {
 	var rowIndex, cellIndex, rowLength, cellLength;
 	var cells = [];
@@ -8,4 +17,4 @@ table.getAllCells = function (tableElm) {
 		}
 	}
 	return cells;
-};
\ No newline at end of file
+};
diff --git a/lib/commons/table/get-cell-position.js b/lib/commons/table/get-cell-position.js
index d587b07cca..c942365401 100644
--- a/lib/commons/table/get-cell-position.js
+++ b/lib/commons/table/get-cell-position.js
@@ -1,9 +1,12 @@
-/*global table, dom */
+/* global table, dom */
 
 /**
  * Get the x, y coordinates of a table cell; normalized for rowspan and colspan
- * @param  {HTMLTableCelLElement} cell The table cell of which to get the position
- * @return {Object}      Object with `x` and `y` properties of the coordinates
+ * @method getCellPosition
+ * @memberof axe.commons.table
+ * @instance
+ * @param  {HTMLTableCellElement} cell The table cell of which to get the position
+ * @return {Object} Object with `x` and `y` properties of the coordinates
  */
 table.getCellPosition = function (cell, tableGrid) {
 	var rowIndex, index;
@@ -23,4 +26,4 @@ table.getCellPosition = function (cell, tableGrid) {
 		}
 	}
 
-};
\ No newline at end of file
+};
diff --git a/lib/commons/table/get-headers.js b/lib/commons/table/get-headers.js
index b9b19b5aff..15b641802b 100644
--- a/lib/commons/table/get-headers.js
+++ b/lib/commons/table/get-headers.js
@@ -1,9 +1,12 @@
-/*global table */
+/* global table */
 
 /**
  * Get any associated table headers for a `HTMLTableCellElement`
+ * @method getHeaders
+ * @memberof axe.commons.table
+ * @instance
  * @param  {HTMLTableCellElement} cell The cell of which to get headers
- * @return {Array}      Array of headers associated to the table cell
+ * @return {Array<HTMLTableCellElement>} Array of headers associated to the table cell
  */
 table.getHeaders = function (cell) {
 
@@ -24,4 +27,4 @@ table.getHeaders = function (cell) {
 	.filter((cell) => table.isColumnHeader(cell));
 
 	return [].concat(rowHeaders, colHeaders).reverse();
-};
\ No newline at end of file
+};
diff --git a/lib/commons/table/get-scope.js b/lib/commons/table/get-scope.js
index 0d2ce03dff..5b6d7d8466 100644
--- a/lib/commons/table/get-scope.js
+++ b/lib/commons/table/get-scope.js
@@ -1,9 +1,12 @@
-/*global table, dom */
+/* global table, dom */
 
 /**
- * Determine if a `HTMLTableCellElement` is a column header
- * @param  {HTMLTableCellElement}  node The table cell to test
- * @return {Boolean}
+ * Determine if a `HTMLTableCellElement` is a column header, if so get the scope of the header
+ * @method getScope
+ * @memberof axe.commons.table
+ * @instance
+ * @param {HTMLTableCellElement} cell The table cell to test
+ * @return {Boolean|String} Returns `false` if not a column header, or the scope of the column header element
  */
 table.getScope = function (cell) {
 	var scope = cell.getAttribute('scope');
@@ -49,4 +52,4 @@ table.getScope = function (cell) {
 		return 'row';
 	}
 	return 'auto';
-};
\ No newline at end of file
+};
diff --git a/lib/commons/table/index.js b/lib/commons/table/index.js
index 35a35d764f..901a727159 100644
--- a/lib/commons/table/index.js
+++ b/lib/commons/table/index.js
@@ -1,2 +1,9 @@
-/*exported table */
+/* exported table */
+
+/**
+ * Namespace for table-related utilities.
+ * @namespace table
+ * @memberof axe.commons
+ */
+
 var table = commons.table = {};
diff --git a/lib/commons/table/is-column-header.js b/lib/commons/table/is-column-header.js
index 83386f1741..0e59f2e9ea 100644
--- a/lib/commons/table/is-column-header.js
+++ b/lib/commons/table/is-column-header.js
@@ -1,10 +1,13 @@
-/*global table */
+/* global table */
 
 /**
  * Determine if a `HTMLTableCellElement` is a column header
- * @param  {HTMLTableCellElement}  node The table cell to test
+ * @method isColumnHeader
+ * @memberof axe.commons.table
+ * @instance
+ * @param  {HTMLTableCellElement} element The table cell to test
  * @return {Boolean}
  */
-table.isColumnHeader = function (node) {
-	return (['col', 'auto'].indexOf(table.getScope(node)) !== -1);
-};
\ No newline at end of file
+table.isColumnHeader = function (element) {
+	return (['col', 'auto'].indexOf(table.getScope(element)) !== -1);
+};
diff --git a/lib/commons/table/is-data-cell.js b/lib/commons/table/is-data-cell.js
index 1593825ee0..0a0b97e3f0 100644
--- a/lib/commons/table/is-data-cell.js
+++ b/lib/commons/table/is-data-cell.js
@@ -1,8 +1,11 @@
-/*global table */
+/* global table */
 
 /**
  * Determine if a `HTMLTableCellElement` is a data cell
- * @param  {HTMLTableCellElement}  node The table cell to test
+ * @method isDataCell
+ * @memberof axe.commons.table
+ * @instance
+ * @param  {HTMLTableCellElement} node The table cell to test
  * @return {Boolean}
  */
 table.isDataCell = function (cell) {
@@ -11,4 +14,4 @@ table.isDataCell = function (cell) {
 		return false;
 	}
 	return cell.nodeName.toUpperCase() === 'TD';
-};
\ No newline at end of file
+};
diff --git a/lib/commons/table/is-data-table.js b/lib/commons/table/is-data-table.js
index 74da5cd49a..5130b3a8d1 100644
--- a/lib/commons/table/is-data-table.js
+++ b/lib/commons/table/is-data-table.js
@@ -1,9 +1,12 @@
-/*global table, dom */
-/*jshint maxstatements: 70, maxcomplexity: 40 */
+/* global table, dom */
+/* jshint maxstatements: 70, maxcomplexity: 40 */
 
 /**
  * Determines whether a table is a data table
- * @param  {HTMLTableElement}  node The table to test
+ * @method isDataTable
+ * @memberof axe.commons.table
+ * @instance
+ * @param  {HTMLTableElement} node The table to test
  * @return {Boolean}
  * @see http://asurkov.blogspot.co.uk/2011/10/data-vs-layout-table.html
  */
diff --git a/lib/commons/table/is-header.js b/lib/commons/table/is-header.js
index 5edcb8df77..69d4890f6b 100644
--- a/lib/commons/table/is-header.js
+++ b/lib/commons/table/is-header.js
@@ -1,8 +1,11 @@
-/*global table, axe */
+/* global table, axe */
 
 /**
  * Determine if a `HTMLTableCellElement` is a header
- * @param  {HTMLTableCellElement}  node The table cell to test
+ * @method isHeader
+ * @memberof axe.commons.table
+ * @instance
+ * @param  {HTMLTableCellElement} cell The table cell to test
  * @return {Boolean}
  */
 table.isHeader = function (cell) {
diff --git a/lib/commons/table/is-row-header.js b/lib/commons/table/is-row-header.js
index e56af7ac17..4a934f8885 100644
--- a/lib/commons/table/is-row-header.js
+++ b/lib/commons/table/is-row-header.js
@@ -1,10 +1,13 @@
-/*global table */
+/* global table */
 
 /**
  * Determine if a `HTMLTableCellElement` is a row header
- * @param  {HTMLTableCellElement}  node The table cell to test
+ * @method isRowHeader
+ * @memberof axe.commons.table
+ * @instance
+ * @param  {HTMLTableCellElement} cell The table cell to test
  * @return {Boolean}
  */
-table.isRowHeader = function (node) {
-	return (['row', 'auto'].includes(table.getScope(node)));
-};
\ No newline at end of file
+table.isRowHeader = function (cell) {
+	return (['row', 'auto'].includes(table.getScope(cell)));
+};
diff --git a/lib/commons/table/to-grid.js b/lib/commons/table/to-grid.js
index 565d203212..74a2566aeb 100644
--- a/lib/commons/table/to-grid.js
+++ b/lib/commons/table/to-grid.js
@@ -2,8 +2,11 @@
 
 /**
  * Converts a table to an Array of arrays, normalized for row and column spans
+ * @method toGrid
+ * @memberof axe.commons.table
+ * @instance
  * @param  {HTMLTableElement} node The table to convert
- * @return {Array}      Array of rows and cells
+ * @return {Array<HTMLTableCellElement>} Array of HTMLTableCellElements
  */
 table.toGrid = function (node) {
 	var table = [];
@@ -32,4 +35,4 @@ table.toGrid = function (node) {
 };
 
 // This was the old name
-table.toArray = table.toGrid;
\ No newline at end of file
+table.toArray = table.toGrid;
diff --git a/lib/commons/table/traverse.js b/lib/commons/table/traverse.js
index 18d9d6b002..c971a82d33 100644
--- a/lib/commons/table/traverse.js
+++ b/lib/commons/table/traverse.js
@@ -23,12 +23,15 @@
 	};
 
 	/**
-	 * Traverses a table in a given direction, passing it to the callback
-	 * @param  {object}   dir      Direction that will be added recursively {x: 1, y: 0};
-	 * @param  {object}   start    x/y coordinate: {x: 0, y: 0};
-	 * @param  {array}    [table]  A matrix of the table obtained using axe.commons.table.toArray (OPTIONAL)
+	 * Traverses a table in a given direction, passing the cell to the callback
+	 * @method traverse
+	 * @memberof axe.commons.table
+	 * @instance
+	 * @param  {Object|String} dir Direction that will be added recursively {x: 1, y: 0}, 'left';
+	 * @param  {Object}   startPos    x/y coordinate: {x: 0, y: 0};
+	 * @param  {Array}    [tablegrid]  A matrix of the table obtained using axe.commons.table.toArray (OPTIONAL)
 	 * @param  {Function} callback Function to which each cell will be passed
-	 * @return {nodeElemtn}        If the callback returns true, the traversal will end and the cell will be returned
+	 * @return {NodeElement}       If the callback returns true, the traversal will end and the cell will be returned
 	 */
 	table.traverse = function (dir, startPos, tableGrid, callback) {
 		if (Array.isArray(startPos)) {
@@ -56,4 +59,4 @@
 		}, tableGrid, callback);
 	};
 
-}(table));
\ No newline at end of file
+}(table));
diff --git a/lib/commons/text/accessible-text-virtual.js b/lib/commons/text/accessible-text-virtual.js
index 002a313f8a..d5401d8a1b 100644
--- a/lib/commons/text/accessible-text-virtual.js
+++ b/lib/commons/text/accessible-text-virtual.js
@@ -1,5 +1,5 @@
-/*global text, dom, aria, axe */
-/*jshint maxstatements: 27, maxcomplexity: 19 */
+/* global text, dom, aria, axe */
+/* jshint maxstatements: 27, maxcomplexity: 19 */
 
 var defaultButtonValues = {
 	submit: 'Submit',
@@ -15,7 +15,7 @@ var phrasingElements = ['A', 'EM', 'STRONG', 'SMALL', 'MARK', 'ABBR', 'DFN', 'I'
 
 /**
  * Find a non-ARIA label for an element
- *
+ * @private
  * @param {HTMLElement} element The HTMLElement
  * @return {HTMLElement} The label element, or null if none is found
  */
@@ -51,7 +51,7 @@ function shouldNeverCheckSubtree({ actualNode }) {
 
 /**
  * Calculate value of a form element when treated as a value
- *
+ * @private
  * @param {HTMLElement} element The HTMLElement
  * @return {string} The calculated value
  */
@@ -88,6 +88,7 @@ function formValueText({ actualNode }) {
 /**
  * Get the accessible text of first matching node
  * IMPORTANT: This method does not look at the composed tree
+ * @private
  */
 function checkDescendant({ actualNode }, nodeName) {
 	var candidate = actualNode.querySelector(nodeName.toLowerCase());
@@ -101,7 +102,7 @@ function checkDescendant({ actualNode }, nodeName) {
 
 /**
  * Determine whether an element can be an embedded control
- *
+ * @private
  * @param {HTMLElement} element The HTMLElement
  * @return {boolean} True if embedded control
  */
@@ -115,7 +116,7 @@ function isEmbeddedControl(elm) {
 		case 'TEXTAREA':
 			return true;
 		case 'INPUT':
-			return (!actualNode.hasAttribute('type') || 
+			return (!actualNode.hasAttribute('type') ||
 					inputTypes.includes(actualNode.getAttribute('type').toLowerCase()));
 		default:
 			return false;
@@ -133,10 +134,11 @@ function nonEmptyText(t) {
 }
 
 /**
- * Determine the accessible text of an element, using logic from ARIA:
- * http://www.w3.org/TR/html-aam-1.0/
- * http://www.w3.org/TR/wai-aria/roles#textalternativecomputation
- *
+ * Finds virtual node and calls accessibleTextVirtual()
+ * IMPORTANT: This method requires the composed tree at axe._tree
+ * @method accessibleText
+ * @memberof axe.commons.text
+ * @instance
  * @param {HTMLElement} element The HTMLElement
  * @param {Boolean} inLabelledByContext True when in the context of resolving a labelledBy
  * @return {string}
@@ -146,6 +148,17 @@ text.accessibleText = function accessibleText(element, inLabelledByContext) {
 	return axe.commons.text.accessibleTextVirtual(virtualNode, inLabelledByContext);
 };
 
+/**
+ * Determine the accessible text of an element, using logic from ARIA:
+ * http://www.w3.org/TR/html-aam-1.0/
+ * http://www.w3.org/TR/wai-aria/roles#textalternativecomputation
+ * @method accessibleTextVirtual
+ * @memberof axe.commons.text
+ * @instance
+ * @param {VirtualNode} element Virtual Node to search
+ * @param {Boolean} inLabelledByContext True when in the context of resolving a labelledBy
+ * @return {string}
+ */
 text.accessibleTextVirtual = function accessibleTextVirtual(element, inLabelledByContext) {
 	let accessibleNameComputation;
 	const encounteredNodes = [];
@@ -248,7 +261,7 @@ text.accessibleTextVirtual = function accessibleTextVirtual(element, inLabelledB
 			}).join(' '));
 		}
 
-		if (!returnText && !(inControlContext && isEmbeddedControl(element)) && 
+		if (!returnText && !(inControlContext && isEmbeddedControl(element)) &&
 				actualNode.hasAttribute('aria-label')) {
 			return text.sanitize(actualNode.getAttribute('aria-label'));
 		}
diff --git a/lib/commons/text/index.js b/lib/commons/text/index.js
index 108d64bd8c..b8e4b503f2 100644
--- a/lib/commons/text/index.js
+++ b/lib/commons/text/index.js
@@ -1,2 +1,9 @@
-/*exported text */
-var text = commons.text = {};
\ No newline at end of file
+/* exported text */
+
+/**
+ * Namespace for text-related utilities.
+ * @namespace text
+ * @memberof axe.commons
+ */
+
+var text = commons.text = {};
diff --git a/lib/commons/text/label-virtual.js b/lib/commons/text/label-virtual.js
index 1f724eec88..7ab7393770 100644
--- a/lib/commons/text/label-virtual.js
+++ b/lib/commons/text/label-virtual.js
@@ -1,9 +1,13 @@
-/*global text, dom, axe, aria */
+/* global text, dom, axe, aria */
+
 /**
  * Gets the visible text of a label for a given input
  * @see http://www.w3.org/WAI/PF/aria/roles#namecalculation
- * @param  {Object} node The virtual node mapping to the input to test
- * @return {Mixed}      String of visible text, or `null` if no label is found
+ * @method labelVirtual
+ * @memberof axe.commons.text
+ * @instance
+ * @param  {VirtualNode} node The virtual node mapping to the input to test
+ * @return {Mixed} String of visible text, or `null` if no label is found
  */
 text.labelVirtual = function (node) {
 	var ref, candidate, doc;
@@ -33,6 +37,16 @@ text.labelVirtual = function (node) {
 	return null;
 };
 
+/**
+ * Finds virtual node and calls labelVirtual()
+ * IMPORTANT: This method requires the composed tree at axe._tree
+ * @see axe.commons.text.virtualLabel
+ * @method label
+ * @memberof axe.commons.text
+ * @instance
+ * @param  {Element} node The virtual node mapping to the input to test
+ * @return {Mixed} String of visible text, or `null` if no label is found
+ */
 text.label = function (node) {
 	node = axe.utils.getNodeFromTree(axe._tree[0], node);
 	return text.labelVirtual(node);
diff --git a/lib/commons/text/sanitize.js b/lib/commons/text/sanitize.js
index 369cefd828..e6411b418b 100644
--- a/lib/commons/text/sanitize.js
+++ b/lib/commons/text/sanitize.js
@@ -1,4 +1,13 @@
-/*global text */
+/* global text */
+
+/**
+ * Removes carriage returns, newline characters, tabs, non-breaking spaces, and trailing spaces from string
+ * @method sanitize
+ * @memberof axe.commons.text
+ * @instance
+ * @param  {String} str String to be cleaned
+ * @return {String} Sanitized string
+ */
 text.sanitize = function (str) {
 	'use strict';
 	return str
diff --git a/lib/commons/text/visible-virtual.js b/lib/commons/text/visible-virtual.js
index 8fb973dfb8..36a600d422 100644
--- a/lib/commons/text/visible-virtual.js
+++ b/lib/commons/text/visible-virtual.js
@@ -1,9 +1,18 @@
-/*global text, dom, axe */
+/* global text, dom, axe */
 
 /**
+ * Returns the visible text of the virtual node
  * NOTE: when calculating the text or accessible text of a node that includes shadow
  * roots attached to it or its children, the flattened tree must be considered
  * rather than the "light DOM"
+ * @method visibleVirtual
+ * @memberof axe.commons.text
+ * @instance
+ * @param  {VirtualNode} element
+ * @param  {Boolean} screenReader When provided, will evaluate visibility from the perspective of a screen reader
+ * @param  {Boolean} noRecursing When False, the result will contain text from the element and it's children.
+ * When True, the result will only contain text from the element
+ * @return {String}
  */
 text.visibleVirtual = function (element, screenReader, noRecursing) {
 	const result = element.children.map(child => {
@@ -20,6 +29,15 @@ text.visibleVirtual = function (element, screenReader, noRecursing) {
 	return text.sanitize(result);
 };
 
+/**
+ * Finds virtual node and calls visibleVirtual()
+ * IMPORTANT: This method requires the composed tree at axe._tree
+ * @param  {Element} element
+ * @param  {Boolean} screenReader When provided, will evaluate visibility from the perspective of a screen reader
+ * @param  {Boolean} noRecursing When False, the result will contain text from the element and it's children.
+ * When True, the result will only contain text from the element
+ * @return {String}
+ */
 text.visible = function (element, screenReader, noRecursing) {
 	element = axe.utils.getNodeFromTree(axe._tree[0], element);
 	return text.visibleVirtual(element, screenReader, noRecursing);
diff --git a/lib/commons/utils/index.js b/lib/commons/utils/index.js
index 8c2d0e801c..fb9a079292 100644
--- a/lib/commons/utils/index.js
+++ b/lib/commons/utils/index.js
@@ -1,4 +1,10 @@
-/*exported utils */
-/*global axe */
-var utils = commons.utils = axe.utils;
+/* exported utils */
+/* global axe */
+
+/**
+ * Namespace for general utilities.
+ * @namespace utils
+ * @memberof axe.commons
+ */
 
+var utils = commons.utils = axe.utils;
diff --git a/lib/commons/utils/to-array.js b/lib/commons/utils/to-array.js
index eb5c170e5e..839b267706 100644
--- a/lib/commons/utils/to-array.js
+++ b/lib/commons/utils/to-array.js
@@ -1,5 +1,14 @@
-/*global axe */
+/* global axe */
+
+/**
+ * Converts thing to an Array
+ * @method toArray
+ * @memberof axe.commons.utils
+ * @instance
+ * @param  {NodeList|HTMLCollection|String} thing
+ * @return {Array}
+ */
 axe.utils.toArray = function (thing) {
 	'use strict';
 	return Array.prototype.slice.call(thing);
-};
\ No newline at end of file
+};
diff --git a/lib/commons/utils/token-list.js b/lib/commons/utils/token-list.js
index 8efccbd152..ae072027da 100644
--- a/lib/commons/utils/token-list.js
+++ b/lib/commons/utils/token-list.js
@@ -1,7 +1,14 @@
-/*global axe */
-
+/* global axe */
+/**
+ * Converts space delimited token list to an Array
+ * @method tokenList
+ * @memberof axe.commons.utils
+ * @instance
+ * @param  {String} str
+ * @return {Array}
+ */
 axe.utils.tokenList = function (str) {
 	'use strict';
 
 	return str.trim().replace(/\s{2,}/g, ' ').split(' ');
-};
\ No newline at end of file
+};
diff --git a/lib/commons/utils/valid-langs.js b/lib/commons/utils/valid-langs.js
index e406e13c76..68d140a6f9 100644
--- a/lib/commons/utils/valid-langs.js
+++ b/lib/commons/utils/valid-langs.js
@@ -1,5 +1,5 @@
-/*global axe */
-/*jshint -W109 */
+/* global axe */
+/* jshint -W109 */
 var langs = [
 	"aa",
 	"ab",
@@ -8128,7 +8128,15 @@ var langs = [
 	"zza",
 	"zzj"
 ];
+
+/**
+ * Returns array of valid language codes
+ * @method validLangs
+ * @memberof axe.commons.utils
+ * @instance
+ * @return {Array<Sting>} Valid language codes
+ */
 axe.utils.validLangs = function () {
 	'use strict';
 	return langs;
-};
\ No newline at end of file
+};
diff --git a/lib/core/utils/contains.js b/lib/core/utils/contains.js
index 777e96a52e..676b1bb882 100644
--- a/lib/core/utils/contains.js
+++ b/lib/core/utils/contains.js
@@ -1,6 +1,9 @@
 
 /**
  * Wrapper for Node#contains; PhantomJS does not support Node#contains and erroneously reports that it does
+ * @method contains
+ * @memberof axe.utils
+ * @instance
  * @param  {HTMLElement} node      The candidate container node
  * @param  {HTMLElement} otherNode The node to test is contained by `node`
  * @return {Boolean}           Whether `node` contains `otherNode`
@@ -27,4 +30,4 @@ axe.utils.contains = function (node, otherNode) {
 
 	return !!(node.actualNode.compareDocumentPosition(otherNode.actualNode) & 16);
 
-};
\ No newline at end of file
+};
diff --git a/lib/core/utils/find-by.js b/lib/core/utils/find-by.js
index c9b8ebf2ab..a649d0ec8e 100644
--- a/lib/core/utils/find-by.js
+++ b/lib/core/utils/find-by.js
@@ -1,6 +1,9 @@
 
 /**
  * Iterates an array of objects looking for a property with a specific value
+ * @method findBy
+ * @memberof axe.utils
+ * @instance
  * @param  {Array} array  The array of objects to iterate
  * @param  {String} key   The property name to test against
  * @param  {Mixed} value  The value to find
@@ -10,4 +13,4 @@ axe.utils.findBy = function (array, key, value) {
 	if (Array.isArray(array)) {
 		return array.find( obj => typeof obj === 'object' && obj[key] === value );
 	}
-};
\ No newline at end of file
+};
diff --git a/lib/core/utils/index.js b/lib/core/utils/index.js
index c85df45266..aee1e38fe6 100644
--- a/lib/core/utils/index.js
+++ b/lib/core/utils/index.js
@@ -1,2 +1,9 @@
-/*exported utils */
+/* exported utils */
+
+/**
+ * Namespace for utility helper methods.
+ * @namespace utils
+ * @memberof axe
+ */
+
 var utils = axe.utils = {};
diff --git a/lib/core/utils/is-hidden.js b/lib/core/utils/is-hidden.js
index e0e3554edc..01065a10e1 100644
--- a/lib/core/utils/is-hidden.js
+++ b/lib/core/utils/is-hidden.js
@@ -2,8 +2,11 @@
 
 /**
  * Determine whether an element is visible
- *
+ * @method isHidden
+ * @memberof axe.utils
+ * @instance
  * @param {HTMLElement} el The HTMLElement
+ * @param {Boolean} recursed
  * @return {Boolean} The element's visibilty status
  */
 axe.utils.isHidden = function isHidden(el, recursed) {
diff --git a/lib/core/utils/qsa.js b/lib/core/utils/qsa.js
index 780be20d6c..861eec9d7f 100644
--- a/lib/core/utils/qsa.js
+++ b/lib/core/utils/qsa.js
@@ -1,8 +1,3 @@
-/**
- * querySelectorAll implementation that works on the virtual DOM and
- * supports shadowDOM
- */
-
 // The lines below is because the latedef option does not work
 var convertExpressions = function () {};
 var matchExpressions = function () {};
@@ -175,9 +170,9 @@ function convertPseudos (pseudos) {
 
 /**
  * convert the css-selector-parser format into the Slick format
- *
- * @param Array{Object} expressions
- * @return Array{Object}
+ * @private
+ * @param Array {Object} expressions
+ * @return Array {Object}
  *
  */
 convertExpressions = function (expressions) {
@@ -215,10 +210,19 @@ matchExpressions = function  (domTree, expressions, recurse) {
 	}, []);
 };
 
+/**
+ * querySelectorAll implementation that operates on the flattened tree (supports shadow DOM)
+ * @method querySelectorAll
+ * @memberof axe.utils
+ * @instance
+ * @param  {NodeList} domTree flattened tree collection to search
+ * @param  {String} selector String containing one or more CSS selectors separated by commas
+ * @return {NodeList} Elements matched by any of the selectors
+ */
 axe.utils.querySelectorAll = function (domTree, selector) {
 	domTree = Array.isArray(domTree) ? domTree : [domTree];
 	var expressions = axe.utils.cssParser.parse(selector);
 	expressions = expressions.selectors ? expressions.selectors : [expressions];
 	expressions = convertExpressions(expressions);
 	return matchExpressions(domTree, expressions, true);
-};
\ No newline at end of file
+};