docs: document check evaluate functions (#2414)

* docs: document check evaluate functions

* Update lib/checks/aria/abstractrole-evaluate.js

Co-authored-by: Wilco Fiers <WilcoFiers@users.noreply.github.com>

* Update lib/checks/aria/fallbackrole-evaluate.js

* Update lib/checks/aria/has-widget-role-evaluate.js

* output data in docs

* finalize docs

Co-authored-by: Wilco Fiers <WilcoFiers@users.noreply.github.com>

.jsdoc.json

@@ -1,5 +1,6 @@
 {
 	"tags": {
+		"allowUnknownTags": true,
 		"dictionaries": ["jsdoc"]
 	},
 	"source": {
@@ -12,5 +13,6 @@
 		"encoding": "utf8",
 		"recurse": true,
 		"template": "./node_modules/minami"
-	}
-}
+	},
+	"plugins": ["plugins/markdown"]
+}

lib/checks/aria/abstractrole-evaluate.js

@@ -1,6 +1,29 @@
 import { tokenList } from '../../core/utils';
 import { getRoleType } from '../../commons/aria';
-
+/**
+ * Check if an element's `role` attribute uses any abstract role values.
+ *
+ * Abstract roles are taken from the `ariaRoles` standards object from the roles `type` property.
+ *
+ * ##### Data:
+ * <table class="props">
+ *   <thead>
+ *     <tr>
+ *       <th>Type</th>
+ *       <th>Description</th>
+ *     </tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr>
+ *       <td><code>String[]</code></td>
+ *       <td>List of all abstract roles</td>
+ *     </tr>
+ *   </tbody>
+ * </table>
+ *
+ * @memberof checks
+ * @return {Boolean} True if the element uses an `abstract` role. False otherwise.
+ */
 function abstractroleEvaluate(node, options, virtualNode) {
 	const abstractRoles = tokenList(virtualNode.attr('role')).filter(
 		role => getRoleType(role) === 'abstract'

lib/checks/aria/aria-allowed-attr-evaluate.js

@@ -1,6 +1,30 @@
 import { getNodeAttributes, uniqueArray } from '../../core/utils';
 import { getRole, allowedAttr, validateAttr } from '../../commons/aria';
 
+/**
+ * Check if each ARIA attribute on an element is allowed for its semantic role.
+ *
+ * Allowed ARIA attributes are taken from the `ariaRoles` standards object combining the roles `requiredAttrs` and `allowedAttrs` properties, as well as any global ARIA attributes from the `ariaAttrs` standards object.
+ *
+ * ##### Data:
+ * <table class="props">
+ *   <thead>
+ *     <tr>
+ *       <th>Type</th>
+ *       <th>Description</th>
+ *     </tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr>
+ *       <td><code>String[]</code></td>
+ *       <td>List of all unallowed aria attributes and their value</td>
+ *     </tr>
+ *   </tbody>
+ * </table>
+ *
+ * @memberof checks
+ * @return {Boolean} True if each aria attribute is allowed. False otherwise.
+ */
 function ariaAllowedAttrEvaluate(node, options) {
 	const invalid = [];
 

lib/checks/aria/aria-allowed-role-evaluate.js

@@ -1,6 +1,17 @@
 import { isVisible } from '../../commons/dom';
 import { getElementUnallowedRoles } from '../../commons/aria';
 
+/**
+ * Check if an element is allowed to have its explicit role value.
+ *
+ * Allowed ARIA roles are taken from the `htmlElms` standards object from the elements `allowedRoles` property.
+ *
+ * @memberof checks
+ * @param {Boolean} [options.allowImplicit=true] Allow the explicit role to match the implicit role of the element.
+ * @param {String[]} [options.ignoredTags=[]] Do not check for allowed roles in the provided HTML elements list.
+ * @data {String[]} List of all unallowed roles.
+ * @return {Boolean} True if the role is allowed on the element. False otherwise.
+ */
 function ariaAllowedRoledEvaluate(node, options = {}) {
 	/**
 	 * Implements allowed roles defined at:

lib/checks/aria/aria-errormessage-evaluate.js

@@ -2,6 +2,28 @@ import standards from '../../standards';
 import { getRootNode } from '../../commons/dom';
 import { tokenList } from '../../core/utils';
 
+/**
+ * Check if an element with `aria-errormessage` also uses a technique to announce the message (aria-live, aria-describedby, etc.).
+ *
+ * ##### Data:
+ * <table class="props">
+ *   <thead>
+ *     <tr>
+ *       <th>Type</th>
+ *       <th>Description</th>
+ *     </tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr>
+ *       <td><code>Boolean</code></td>
+ *       <td>The value of the `aria-errormessage` attribute</td>
+ *     </tr>
+ *   </tbody>
+ * </table>
+ *
+ * @memberof checks
+ * @return {Boolean} True if the element uses a supported technique. False otherwise.
+ */
 function ariaErrormessageEvaluate(node, options) {
 	options = Array.isArray(options) ? options : [];
 

lib/checks/aria/aria-hidden-body-evaluate.js

@@ -1,3 +1,9 @@
+/**
+ * Check that the element does not have the `aria-hidden` attribute.
+ *
+ * @memberof checks
+ * @return {Boolean} True if the `aria-hidden` attribute is not present. False otherwise.
+ */
 function ariaHiddenBodyEvaluate(node, options, virtualNode) {
 	return virtualNode.attr('aria-hidden') !== 'true';
 }

lib/checks/aria/aria-required-attr-evaluate.js

@@ -2,6 +2,30 @@ import { requiredAttr } from '../../commons/aria';
 import { getElementSpec } from '../../commons/standards';
 import { uniqueArray, getNodeFromTree } from '../../core/utils';
 
+/**
+ * Check that the element has all required attributes for its explicit role.
+ *
+ * Required ARIA attributes are taken from the `ariaRoles` standards object from the roles `requiredAttrs` property.
+ *
+ * ##### Data:
+ * <table class="props">
+ *   <thead>
+ *     <tr>
+ *       <th>Type</th>
+ *       <th>Description</th>
+ *     </tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr>
+ *       <td><code>String[]</code></td>
+ *       <td>List of all missing require attributes</td>
+ *     </tr>
+ *   </tbody>
+ * </table>
+ *
+ * @memberof checks
+ * @return {Boolean} True if all required attributes are present. False otherwise.
+ */
 function ariaRequiredAttrEvaluate(node, options = {}) {
 	const vNode = getNodeFromTree(node);
 	const missing = [];

lib/checks/aria/aria-required-children-evaluate.js

@@ -84,6 +84,16 @@ function missingRequiredChildren(virtualNode, role, required, ownedRoles) {
 	return null;
 }
 
+/**
+ * Check that an element owns all required children for its explicit role.
+ *
+ * Required roles are taken from the `ariaRoles` standards object from the roles `requiredOwned` property.
+ *
+ * @memberof checks
+ * @param {Boolean} options.reviewEmpty List of ARIA roles that should be flagged as "Needs Review" rather than a violation if the element has no owned children.
+ * @data {String[]} List of all missing owned roles.
+ * @returns {Mixed} True if the element owns all required roles. Undefined if `options.reviewEmpty=true` and the element has no owned children. False otherwise.
+ */
 function ariaRequiredChildrenEvaluate(node, options, virtualNode) {
 	const reviewEmpty =
 		options && Array.isArray(options.reviewEmpty) ? options.reviewEmpty : [];

lib/checks/aria/aria-required-parent-evaluate.js

@@ -50,6 +50,30 @@ function getAriaOwners(element) {
 	return owners.length ? owners : null;
 }
 
+/**
+ * Check if the element has a parent with a required role.
+ *
+ * Required parent roles are taken from the `ariaRoles` standards object from the roles `requiredContext` property.
+ *
+ * ##### Data:
+ * <table class="props">
+ *   <thead>
+ *     <tr>
+ *       <th>Type</th>
+ *       <th>Description</th>
+ *     </tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr>
+ *       <td><code>String[]</code></td>
+ *       <td>List of all missing required parent roles</td>
+ *     </tr>
+ *   </tbody>
+ * </table>
+ *
+ * @memberof checks
+ * @return {Boolean} True if the element has a parent with a required role. False otherwise.
+ */
 function ariaRequiredParentEvaluate(node, options, virtualNode) {
 	var missingParents = getMissingContext(virtualNode);
 

lib/checks/aria/aria-roledescription-evaluate.js

@@ -1,5 +1,12 @@
 import { getRole } from '../../commons/aria';
 
+/**
+ * Check that `aria-roledescription` is used on a supported semantic role.
+ *
+ * @memberof checks
+ * @param {String[]} options.supportedRoles List of ARIA roles that support the `aria-roledescription` attribute
+ * @return {Mixed} True if the semantic role supports `aria-roledescription`. Undefined if the semantic role is `presentation` or `none`. False otherwise.
+ */
 function ariaRoledescriptionEvaluate(node, options = {}) {
 	const role = getRole(node);
 	const supportedRoles = options.supportedRoles || [];

lib/checks/aria/aria-unsupported-attr-evaluate.js

@@ -3,6 +3,30 @@ import standards from '../../standards';
 import matches from '../../commons/matches';
 import { getNodeAttributes } from '../../core/utils';
 
+/**
+ * Check that an element does not use any unsupported ARIA attributes.
+ *
+ * Unsupported attributes are taken from the `ariaAttrs` standards object from the attributes `unsupported` property.
+ *
+ * ##### Data:
+ * <table class="props">
+ *   <thead>
+ *     <tr>
+ *       <th>Type</th>
+ *       <th>Description</th>
+ *     </tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr>
+ *       <td><code>String[]</code></td>
+ *       <td>List of all unsupported attributes</td>
+ *     </tr>
+ *   </tbody>
+ * </table>
+ *
+ * @memberof checks
+ * @return {Boolean} True if the element does not use any unsupported ARIA attributes. False otherwise.
+ */
 function ariaUnsupportedAttrEvaluate(node) {
 	const unsupportedAttrs = Array.from(getNodeAttributes(node))
 		.filter(({ name }) => {

lib/checks/aria/aria-valid-attr-evaluate.js

@@ -1,6 +1,30 @@
 import { validateAttr } from '../../commons/aria';
 import { getNodeAttributes } from '../../core/utils';
 
+/**
+ * Check that each `aria-` attribute on an element is a valid ARIA attribute.
+ *
+ * Valid ARIA attributes are listed in the `ariaAttrs` standards object.
+ *
+ * ##### Data:
+ * <table class="props">
+ *   <thead>
+ *     <tr>
+ *       <th>Type</th>
+ *       <th>Description</th>
+ *     </tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr>
+ *       <td><code>String[]</code></td>
+ *       <td>List of all invalid attributes</td>
+ *     </tr>
+ *   </tbody>
+ * </table>
+ *
+ * @memberof checks
+ * @return {Boolean} True if all `aria-` attributes are valid. False otherwise.
+ */
 function ariaValidAttrEvaluate(node, options) {
 	options = Array.isArray(options.value) ? options.value : [];
 

lib/checks/aria/aria-valid-attr-value-evaluate.js

@@ -1,6 +1,30 @@
 import { validateAttrValue } from '../../commons/aria';
 import { getNodeAttributes } from '../../core/utils';
 
+/**
+ * Check that each ARIA attribute on an element has a valid value.
+ *
+ * Valid ARIA attribute values are taken from the `ariaAttrs` standards object from an attributes `type` property.
+ *
+ * ##### Data:
+ * <table class="props">
+ *   <thead>
+ *     <tr>
+ *       <th>Type</th>
+ *       <th>Description</th>
+ *     </tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr>
+ *       <td><code>Mixed</code></td>
+ *       <td>Object with Strings `messageKey` and `needsReview` if `aria-current` or `aria-describedby` are invalid. Otherwise a list of all invalid ARIA attributes and their value</td>
+ *     </tr>
+ *   </tbody>
+ * </table>
+ *
+ * @memberof checks
+ * @return {Mixed} True if all ARIA attributes have a valid value. Undefined for invalid `aria-current` or `aria-describedby` values. False otherwise.
+ */
 function ariaValidAttrValueEvaluate(node, options) {
 	options = Array.isArray(options.value) ? options.value : [];
 

lib/checks/aria/fallbackrole-evaluate.js

@@ -1,5 +1,11 @@
 import { tokenList } from '../../core/utils';
 
+/**
+ * Check that an element does not use more than one explicit role.
+ *
+ * @memberof checks
+ * @return {Boolean} True if the element uses more than one explicit role. False otherwise.
+ */
 function fallbackroleEvaluate(node, options, virtualNode) {
 	return tokenList(virtualNode.attr('role')).length > 1;
 }

lib/checks/aria/has-widget-role-evaluate.js

@@ -1,5 +1,13 @@
 import { getRoleType } from '../../commons/aria';
 
+/**
+ * Check if an elements `role` attribute uses any widget or composite role values.
+ *
+ * Widget roles are taken from the `ariaRoles` standards object from the roles `type` property.
+ *
+ * @memberof checks
+ * @return {Boolean} True if the element uses a `widget` or `composite` role. False otherwise.
+ */
 function hasWidgetRoleEvaluate(node) {
 	const role = node.getAttribute('role');
 	if (role === null) {

lib/checks/aria/invalidrole-evaluate.js

@@ -1,6 +1,30 @@
 import { isValidRole } from '../../commons/aria';
 import { tokenList } from '../../core/utils';
 
+/**
+ * Check that each role on an element is a valid ARIA role.
+ *
+ * Valid ARIA roles are listed in the `ariaRoles` standards object.
+ *
+ * ##### Data:
+ * <table class="props">
+ *   <thead>
+ *     <tr>
+ *       <th>Type</th>
+ *       <th>Description</th>
+ *     </tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr>
+ *       <td><code>String[]</code></td>
+ *       <td>List of all invalid roles</td>
+ *     </tr>
+ *   </tbody>
+ * </table>
+ *
+ * @memberof checks
+ * @return {Boolean} True if the element uses an invalid role. False otherwise.
+ */
 function invalidroleEvaluate(node, options, virtualNode) {
 	const allRoles = tokenList(virtualNode.attr('role'));
 	const allInvalid = allRoles.every(