docs: update jsdoc formatted comments for axe.common methods (dequela…

…bs#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

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

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 = {};
 

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

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
  */

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

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;
+color.elementIsDistinct = elementIsDistinct;

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

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

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 = {};

lib/commons/color/index.js

@@ -1,2 +1,8 @@
+/**
+ * Namespace for color-related utilities.
+ * @namespace commons.color
+ * @memberof axe
+ */
+
 var color = {};
 commons.color = color;