Rule docs (#30)

* Adding/adjusting docs for rules. Adding comments and doc properties to all rules. Fixing broken links in rule messages.

Author: scalvert

guides/rules/no-timers.md renamed to guides/rules/linkedin/no-timers.md

@@ -1,9 +1,14 @@
-const { isInActions, isInteractive } = require('../utils/interactive');
-const { isBrowser, isEnvironmentBrowser } = require('../utils/linkedin/bpr');
+/**
+ * @fileOverview Disallow use of unguarded timers, which can result in issues within the BPR.
+ * @author Steve Calvert
+ */
+
+const { isInActions, isInteractive } = require('../../utils/interactive');
+const { isBrowser, isEnvironmentBrowser } = require('../../utils/linkedin/bpr');
 
 const TIMERS = ['setTimeout', 'setInterval'];
 
-const MESSAGE = 'Do not use timers. Please see the following guide for more infromation: http://github.com/chadhietala/ember-best-practices/files/guides/no-timers.md';
+const MESSAGE = 'Do not use timers. Please see the following guide for more infromation: http://github.com/chadhietala/ember-best-practices/blob/master/guides/rules/linkedin/no-timers.md';
 
 function isTimer(name) {
   return TIMERS.includes(name);
@@ -18,6 +23,11 @@ function getName(node) {
 }
 
 module.exports = {
+  docs: {
+    description: 'Disallow use of unguarded timers, which can result in issues within the BPR',
+    category: 'Best Practices',
+    recommended: false
+  },
   meta: {
     message: MESSAGE
   },

lib/rules/no-timers.js renamed to lib/rules/linkedin/no-timers.js

@@ -9,12 +9,12 @@ const { isBrowser, isEnvironmentBrowser, getEnvironmentImportBinding } = require
 const { isInActions, isInteractive } = require('../../utils/interactive');
 const { collectObjectPatternBindings } = require('../../utils/destructed-binding');
 
-const MESSAGE = 'Do not use unguarded document references. Please see the following guide for more infromation: http://github.com/chadhietala/ember-best-practices/files/guides/no-unguarded-document.md';
+const MESSAGE = 'Do not use unguarded document references. Please see the following guide for more infromation: http://github.com/chadhietala/ember-best-practices/blob/master/guides/rules/linkedin/no-unguarded-document.md';
 
 /**
  * Determines if the current node is a document reference.
  * @param {ASTNode} node The identifier node.
- * @returns {Boolean} Returns true if a document reference is found, else false.
+ * @returns {Boolean} Returns true if a document reference is found, otherwise false.
  */
 function isDocumentReference(node) {
   return get(node, 'callee.object.name') === 'document';

lib/rules/linkedin/no-unguarded-document.js

@@ -9,12 +9,12 @@ const { isBrowser, isEnvironmentBrowser, getEnvironmentImportBinding } = require
 const { isInActions, isInteractive } = require('../../utils/interactive');
 const { collectObjectPatternBindings } = require('../../utils/destructed-binding');
 
-const MESSAGE = 'Do not use unguarded window references. Please see the following guide for more infromation: http://github.com/chadhietala/ember-best-practices/files/guides/no-unguarded-window.md';
+const MESSAGE = 'Do not use unguarded window references. Please see the following guide for more infromation: http://github.com/chadhietala/ember-best-practices/blob/master/guides/rules/linkedin/no-unguarded-window.md';
 
 /**
  * Determines if the current node is a window reference.
  * @param {ASTNode} node The identifier node.
- * @returns {Boolean} Returns true if a window reference is found, else false.
+ * @returns {Boolean} Returns true if a window reference is found, otherwise false.
  */
 function isWindowReference(node) {
   return get(node, 'object.name') === 'window';

lib/rules/linkedin/no-unguarded-window.js

@@ -1,9 +1,20 @@
+/**
+ * @fileOverview Don't use Ember 2.0.0 hooks.
+ * @author Chad Hietala
+ */
+'use strict';
+
 // TODO
 // Write docs for this once we feel it should be recommended.
 const MESSAGE = 'Do not use the 2.0.0 hooks as they are not conducive to the programming model.';
 const MISTAKE_HOOKS = ['didInitAttrs', 'didReceiveAttrs', 'didUpdateAttrs', 'didRender', 'willUpdate', 'didUpdate', 'willRender'];
 
 module.exports = {
+  docs: {
+    description: 'Don\'t use Ember 2.0.0 hooks',
+    category: 'Best Practices',
+    recommended: false
+  },
   meta: {
     message: MESSAGE
   },

lib/rules/no-2.0.0-hooks.js

@@ -1,5 +1,18 @@
+/**
+ * @fileOverview Disallow use of attrs snapshot in `didReceiveAttrs` and `didUpdateAttrs`.
+ * @author Chad Hietala
+ */
+'use strict';
+
 const { get } = require('../utils/get');
 
+/**
+ * Determines if `didReceiveAttrs` or `didUpdateAttrs` are recieving parameters. If so,
+ * this indicates the `attrs` snapshots are being used within those methods.
+ * @param {ASTNode} node The identifier node.
+ * @returns {Boolean} Returns true if either `didReceiveAttrs` or `didUpdateAttrs` are utilizing
+ *                    a parameter containing `attrs`, otherwise false.
+ */
 function hasAttrsSnapShot(node) {
   let methodName = get(node, 'parent.key.name');
   let hasParams = node.params.length > 0;
@@ -9,6 +22,11 @@ function hasAttrsSnapShot(node) {
 const MESSAGE = 'Do not use the attrs snapshot that is passed in `didReceiveAttrs` and `didUpdateAttrs`. Please see the following guide for more infromation: https://github.com/chadhietala/ember-best-practices/blob/master/guides/rules/no-attrs-snapshot.md';
 
 module.exports = {
+  docs: {
+    description: 'Disallow use of attrs snapshot in `didReceiveAttrs` and `didUpdateAttrs`',
+    category: 'Best Practices',
+    recommended: true
+  },
   meta: {
     message: MESSAGE
   },

lib/rules/no-attrs-snapshot.js

@@ -1,10 +1,26 @@
+/**
+ * @fileOverview Disallow the use of `this.attrs`.
+ * @author Chad Hietala
+ */
+'use strict';
+
+/**
+ * Determines if this expression matches `this.attrs`.
+ * @param {ASTNode} node The identifier node.
+ * @returns {Boolean} Returns true if the expression matches, otherwise false.
+ */
 function isAttrs(node) {
   return node.property.name === 'attrs' && node.object.type === 'ThisExpression';
 }
 
 const MESSAGE = 'Do not use this.attrs. Please see the following guide for more infromation: https://github.com/chadhietala/ember-best-practices/blob/master/guides/rules/no-attrs.md';
 
 module.exports = {
+  docs: {
+    description: 'Disallow the use of `this.attrs`',
+    category: 'Best Practices',
+    recommended: true
+  },
   meta: {
     message: MESSAGE
   },

lib/rules/no-attrs.js

@@ -1,3 +1,12 @@
+/**
+ * @fileOverview Disallow use of lifecycle events using `.on()`.
+ * @author Chad Hietala
+ */
+'use strict';
+
+const { collectObjectPatternBindings } = require('../utils/destructed-binding');
+const { getEmberImportBinding } = require('../utils/imports');
+
 const MESSAGE = 'Do not use events for lifecycle hooks. Please use the actual hooks instead: https://github.com/chadhietala/ember-best-practices/blob/master/guides/rules/no-lifecycle-events.md';
 
 function isOn(node) {
@@ -8,18 +17,25 @@ function isEmber(node) {
   return node.name === 'Ember';
 }
 
-const { collectObjectPatternBindings } = require('../utils/destructed-binding');
-const { getEmberImportBinding } = require('../utils/imports');
-
 module.exports = {
+  docs: {
+    description: 'Disallow use of lifecycle events using `.on()`',
+    category: 'Best Practices',
+    recommended: true
+  },
   meta: {
     message: MESSAGE
   },
   create(context) {
     var emberImportBinding;
     let destructedBindings = [];
+
     return {
       ObjectPattern(node) {
+        /**
+         * Retrieves the deconstructed bindings from the Ember import, accounting for aliasing
+         * of the import.
+         */
         if (emberImportBinding) {
           destructedBindings = destructedBindings.concat(collectObjectPatternBindings(node, {
             [emberImportBinding]: ['on']

lib/rules/no-lifecycle-events.js

@@ -1,3 +1,7 @@
+/**
+ * @fileOverview Disallow use of observers.
+ * @author Chad Hietala
+ */
 'use strict';
 
 function isObserver(node) {
@@ -9,6 +13,11 @@ function isObserver(node) {
 const MESSAGE = 'Do not use observers. Consider using computed properties instead. Please see following guide for more information: https://github.com/chadhietala/ember-best-practices/blob/master/guides/rules/no-observers.md';
 
 module.exports = {
+  docs: {
+    description: 'Disallow use of observers',
+    category: 'Best Practices',
+    recommended: true
+  },
   meta: {
     message: MESSAGE
   },

lib/rules/no-observers.js

@@ -1,13 +1,23 @@
+/**
+ * @fileOverview Disallow use of computed properties that include side-effect producing calls.
+ * @author Chad Hietala
+ */
+
 const { getCaller, cleanCaller } = require('../utils/caller');
 const isCPGetter = require('../utils/computed-property');
 const { getEmberImportBinding, collectImportBindings } = require('../utils/imports');
 const { collectObjectPatternBindings } = require('../utils/destructed-binding');
 
 let SIDE_EFFECTS = ['this.send', 'this.sendAction', 'this.sendEvent', 'Em.sendEvent', 'Ember.sendEvent', 'this.trigger', 'this.set', 'Ember.set', 'Em.set', 'this.setProperties', 'Ember.setProperties', 'Em.setProperties'];
 
-const MESSAGE = 'Do not send events or actions in Computed Properties. This will cause data flow issues in the application, where the accessing of a property causes some side-effect. You should only send actions on behalf of user initiated events. Please see the following guide for more infromation: https://github.com/chadhietala/ember-best-practices/blob/master/guides/rules/no-action-cp.md';
+const MESSAGE = 'Do not send events or actions in Computed Properties. This will cause data flow issues in the application, where the accessing of a property causes some side-effect. You should only send actions on behalf of user initiated events. Please see the following guide for more infromation: https://github.com/chadhietala/ember-best-practices/blob/master/guides/rules/no-side-effect-cp.md';
 
 module.exports = {
+  docs: {
+    description: 'Disallow use of computed properties that include side-effect producing calls',
+    category: 'Best Practices',
+    recommended: true
+  },
   meta: {
     message: MESSAGE
   },