Add documentation for utils

Author: remcohaszing

rules/utils/utils.js

@@ -54,7 +54,11 @@ module.exports = {
 };
 
 
-// this will recursively grab the callee until it hits an Identifier
+/**
+ * Recursively grab the callee until an Identifier is found.
+ *
+ * @todo Needs better documentation.
+ */
 function getCallingIdentifier(calleeObject) {
     if (calleeObject.type && calleeObject.type === 'Identifier') {
         return calleeObject;
@@ -65,6 +69,14 @@ function getCallingIdentifier(calleeObject) {
     return null;
 }
 
+/**
+ * Convert a prefix string to a RegExp.
+ *
+ * `'/app/'` → `/app.*\/`
+ *
+ * @param {string} prefix
+ * @returns {RegExp}
+ */
 function convertPrefixToRegex(prefix) {
     if (typeof prefix !== 'string') {
         return prefix;
@@ -77,17 +89,35 @@ function convertPrefixToRegex(prefix) {
     return new RegExp(prefix + '.*');
 }
 
+/**
+ * Convert a string to a RegExp.
+ *
+ * `'app'` → `/app/`
+ * `'/app/'` → `/app/`
+ *
+ * @param {string} prefix
+ * @returns {RegExp}
+ */
 function convertStringToRegex(string) {
     if (string[0] === '/' && string[string.length - 1] === '/') {
         string = string.substring(1, string.length - 2);
     }
     return new RegExp(string);
 }
 
+/**
+ * @todo Missing documentation
+ */
 function isTypeOfStatement(node) {
     return node.type === 'Identifier' || (node.type === 'UnaryExpression' && node.operator === 'typeof');
 }
 
+/**
+ * @todo Missing documentation
+ *
+ * @param {Object} node The node to check.
+ * @returns {boolean} Whether or not the node is a `toString` statement.
+ */
 function isToStringStatement(node) {
     return node.type === 'CallExpression' &&
         node.callee.type === 'MemberExpression' &&
@@ -99,60 +129,183 @@ function isToStringStatement(node) {
         node.callee.object.object.property.name === 'prototype';
 }
 
+/**
+ * Check whether or not a node is an ArrayExpression.
+ *
+ * @param {Object} node The node to check.
+ * @returns {boolean} Whether or not the node is an ArrayExpression.
+ */
 function isArrayType(node) {
     return node !== undefined && node.type === 'ArrayExpression';
 }
 
+/**
+ * Check whether or not a node is an FunctionExpression.
+ *
+ * @param {Object} node The node to check.
+ * @returns {boolean} Whether or not the node is an FunctionExpression.
+ */
 function isFunctionType(node) {
     return node !== undefined && node.type === 'FunctionExpression';
 }
 
+/**
+ * Check whether or not a node is an Identifier.
+ *
+ * @param {Object} node The node to check.
+ * @returns {boolean} Whether or not the node is an Identifier.
+ */
 function isIdentifierType(node) {
     return node !== undefined && node.type === 'Identifier';
 }
 
+/**
+ * Check whether or not a node is an MemberExpression.
+ *
+ * @param {Object} node The node to check.
+ * @returns {boolean} Whether or not the node is an MemberExpression.
+ */
 function isMemberExpression(node) {
     return node !== undefined && node.type === 'MemberExpression';
 }
 
+/**
+ * Check whether or not a node is an Literal.
+ *
+ * @param {Object} node The node to check.
+ * @returns {boolean} Whether or not the node is an Literal.
+ */
 function isLiteralType(node) {
     return node !== undefined && node.type === 'Literal';
 }
 
+/**
+ * Check whether or not a node is an isEmptyFunction.
+ *
+ * @param {Object} node The node to check.
+ * @returns {boolean} Whether or not the node is an isEmptyFunction.
+ */
 function isEmptyFunction(fn) {
     return fn.body.body.length === 0;
 }
 
+/**
+ * Check whether or not an object is a RegExp object.
+ *
+ * @param regexp The object for which to check if it is a RegExp object.
+ * @returns {boolean} Shether or not an object is a RegExp object.
+ */
 function isRegexp(regexp) {
     return toString.call(regexp) === '[object RegExp]';
 }
 
+/**
+ * Check whether or not a string resembles a regular expression.
+ *
+ * A string is considered a regular expression if it starts and ends with `/`.
+ *
+ * @param {string} The string to check.
+ * @returns {boolean} Whether or not a string resembles a regular expression.
+ */
 function isStringRegexp(string) {
     return string[0] === '/' && string[string.length - 1] === '/';
 }
 
+/**
+ * Check if a CallExpression node somewhat resembles an Angular component.
+ *
+ * The following are considered Angular components
+ * ```js
+ * app.factory('kittenService', function() {})
+ *     ^^^^^^^
+ * app.factory('kittenService', kittenService)
+ *     ^^^^^^^
+ * app.factory('kittenService', [])
+ *     ^^^^^^^
+ * asyncFn('value', callback)
+ * ^^^^^^^
+ * ```
+ *
+ * @todo FIXME
+ *
+ * @param {Object} node The CallExpression node to check.
+ * @returns {boolean} Whether or not the node somewhat resembles an Angular component.
+ */
 function isAngularComponent(node) {
-    return node.arguments !== undefined && node.arguments.length === 2 && isLiteralType(node.arguments[0]) && (isIdentifierType(node.arguments[1]) || isFunctionType(node.arguments[1]) || isArrayType(node.arguments[1]));
+    return node.arguments !== undefined &&
+        node.arguments.length === 2 &&
+        isLiteralType(node.arguments[0]) &&
+        (isIdentifierType(node.arguments[1]) ||
+         isFunctionType(node.arguments[1]) ||
+         isArrayType(node.arguments[1]));
 }
 
+/**
+ * Check whether a CallExpression node defines an Angular controller.
+ *
+ * @param {Object} node The CallExpression node to check.
+ * @returns {boolean} Whether or not the node defines an Angular controller.
+ */
 function isAngularControllerDeclaration(node) {
     return isAngularComponent(node) &&
         isMemberExpression(node.callee) &&
         node.callee.property.name === 'controller';
 }
 
+/**
+ * Check whether a CallExpression node defines an Angular filter.
+ *
+ * @param {Object} node The CallExpression node to check.
+ * @returns {boolean} Whether or not the node defines an Angular filter.
+ */
 function isAngularFilterDeclaration(node) {
     return isAngularComponent(node) &&
         isMemberExpression(node.callee) &&
         node.callee.property.name === 'filter';
 }
 
+/**
+ * Check whether a CallExpression node defines an Angular directive.
+ *
+ * @param {Object} node The CallExpression node to check.
+ * @returns {boolean} Whether or not the node defines an Angular directive.
+ */
 function isAngularDirectiveDeclaration(node) {
     return isAngularComponent(node) &&
         isMemberExpression(node.callee) &&
         node.callee.property.name === 'directive';
 }
 
+/**
+ * Check whether a node defines an Angular service.
+ *
+ * The following are considered services
+ * ```js
+ * app.provider('kittenServiceProvider', function() {})
+ *     ^^^^^^^^
+ * app.factory('kittenService', function() {})
+ *     ^^^^^^^
+ * app.service('kittenService', function() {})
+ *     ^^^^^^^
+ * app.constant('KITTENS', function() {})
+ *     ^^^^^^^^
+ * app.value('KITTENS', function() {})
+ *     ^^^^^
+ * ```
+ *
+ * The following are not considered services
+ * ```js
+ * $provide.factory('kittenService', function() {})
+ * app.constant('KITTENS', 'meow')
+ * app.value('KITTENS', 'purr')
+ * this.$get = function() {}
+ * ```
+ *
+ * @todo FIXME
+ *
+ * @param {Object} node The CallExpression node to check.
+ * @returns {boolean} Whether or not the node defines an Angular controller.
+ */
 function isAngularServiceDeclaration(node) {
     return isAngularComponent(node) &&
         isMemberExpression(node.callee) &&
@@ -164,12 +317,24 @@ function isAngularServiceDeclaration(node) {
          node.callee.property.name === 'value');
 }
 
+/**
+ * Check whether a CallExpression node declares an Angular module.
+ *
+ * @param {Object} node The CallExpression node to check.
+ * @returns {boolean} Whether or not the node declares an Angular module.
+ */
 function isAngularModuleDeclaration(node) {
     return isAngularComponent(node) &&
         isMemberExpression(node.callee) &&
         node.callee.property.name === 'module';
 }
 
+/**
+ * Check whether a CallExpression node gets or declares an Angular module.
+ *
+ * @param {Object} node The CallExpression node to check.
+ * @returns {boolean} Whether or not the node gets or declares an Angular module.
+ */
 function isAngularModuleGetter(node) {
     return node.arguments !== undefined &&
         node.arguments.length > 0 &&
@@ -178,6 +343,29 @@ function isAngularModuleGetter(node) {
         node.callee.property.name === 'module';
 }
 
+/**
+ * Check whether a CallExpression node defines an Angular run function.
+ *
+ * The following are considered run functions
+ * ```js
+ * app.run()
+ *     ^^^
+ * app.run(function() {})
+ *     ^^^
+ * ```
+ *
+ * The following are not considered run functions
+ * ```js
+ * angular.module('myApp').run(function() {})
+ * angular.module('myApp', []).run(function() {})
+ * mocha.run()
+ * ```
+ *
+ * @todo FIXME
+ *
+ * @param {Object} node The CallExpression node to check.
+ * @returns {boolean} Whether or not the node defines an Angular run function.
+ */
 function isAngularRunSection(node) {
     return isMemberExpression(node.callee) &&
         node.callee.property.type === 'Identifier' &&
@@ -186,12 +374,46 @@ function isAngularRunSection(node) {
          node.callee.object.name !== 'mocha');
 }
 
+/**
+ * Check whether a CallExpression node defines an Angular config function.
+ *
+ * The following are considered config functions
+ * ```js
+ * app.config()
+ *     ^^^^^^
+ * app.config(function() {})
+ *     ^^^^^^
+ * ```
+ *
+ * The following are not considered run functions
+ * ```js
+ * angular.module('myApp').config(function() {})
+ * angular.module('myApp', []).config(function() {})
+ * ```
+ *
+ * @todo FIXME
+ *
+ * @param {Object} node The CallExpression node to check.
+ * @returns {boolean} Whether or not the node defines an Angular config function.
+ */
 function isAngularConfigSection(node) {
     return isMemberExpression(node.callee) &&
      node.callee.property.type === 'Identifier' &&
      node.callee.property.name === 'config';
 }
 
+/**
+ * Check whether a CallExpression node defines a route using $routeProvider.
+ *
+ * The following are considered routes:
+ * ```js
+ * $routeProvider.when()
+ *                ^^^^
+ * ```
+ *
+ * @param {Object} node The CallExpression node to check.
+ * @returns {boolean} Whether or not the node defines a route.
+ */
 function isRouteDefinition(node) {
     // the route def function is .when(), so when we find that, go up through the chain and make sure
     // $routeProvider is the calling object
@@ -202,6 +424,18 @@ function isRouteDefinition(node) {
     return false;
 }
 
+/**
+ * Check whether a CallExpression node defines a state using $stateProvider.
+ *
+ * The following are considered states:
+ * ```js
+ * $stateProvider.state()
+ *                ^^^^^
+ * ```
+ *
+ * @param {Object} node The CallExpression node to check.
+ * @returns {boolean} Whether or not the node defines a state.
+ */
 function isUIRouterStateDefinition(node) {
     // the state def function is .state(), so when we find that, go up through the chain and make sure
     // $stateProvider is the calling object
@@ -212,6 +446,14 @@ function isUIRouterStateDefinition(node) {
     return false;
 }
 
+/**
+ * Find an identifier node in the current scope.
+ *
+ * @param {Object} context The context to use to get the scope.
+ * @param {Object} identifier The identifier node to look up.
+ *
+ * @returns {Object} The node declaring the identifier.
+ */
 function findIdentiferInScope(context, identifier) {
     var identifierNode = null;
     context.getScope().variables.forEach(function(variable) {
@@ -225,6 +467,14 @@ function findIdentiferInScope(context, identifier) {
     return identifierNode;
 }
 
+/**
+ * Find the function definition of a controller in the current context.
+ *
+ * @param {Object} context The context to use to find the controller declaration.
+ * @param {Object} node The Angular controller call to look up the declaration for.
+ *
+ * @returns {Object} The identifier declaring the controller function.
+ */
 function getControllerDefinition(context, node) {
     var controllerArg = node.arguments[1];