🎨 Tidy up and comment functions

.eslintrc

@@ -135,8 +135,12 @@ rules:
     - global
   valid-jsdoc:
     - 2
-    - prefer:
-        return: returns
+    -
+      requireParamDescription: true
+      requireReturnDescription: true
+      requireReturn: false
+      prefer:
+        return: "returns"
   wrap-iife: 2
   yoda:
     - 2

lib/ruleToggler.js

@@ -1,19 +1,51 @@
 'use strict';
 
+/**
+ * Adds each rule in our array of rules in a disable comment into the toggledRules object
+ * under the correct rule name along with the line an column number where the disable comment
+ * was encountered
+ *
+ * @param {Object} toggledRules - Contains the information about each rule disable/enable
+                                  encountered and and what line/column it occurred on
+ * @param {Array} rules - An array of rule names
+ * @param {number} line - The line number the disable appeared on
+ * @param {number} column - The column number the disable appeared on
+ */
 var addDisable = function (toggledRules, rules, line, column) {
   rules.map(function (rule) {
     toggledRules.ruleEnable[rule] = toggledRules.ruleEnable[rule] || [];
     toggledRules.ruleEnable[rule].push([false, line, column]);
   });
 };
 
+/**
+ * Adds each rule in our array of rules in a enable comment into the toggledRules object
+ * under the correct rule name along with the line an column number where the enable comment
+ * was encountered
+ *
+ * @param {Object} toggledRules - Contains the information about each rule enable
+                                  encountered and and what line/column it occurred on
+ * @param {Array} rules - An array of rule names
+ * @param {number} line - The line number the enable appeared on
+ * @param {number} column - The column number the enable appeared on
+ */
 var addEnable = function (toggledRules, rules, line, column) {
   rules.map(function (rule) {
     toggledRules.ruleEnable[rule] = toggledRules.ruleEnable[rule] || [];
     toggledRules.ruleEnable[rule].push([true, line, column]);
   });
 };
 
+/**
+ * Adds each rule in our array of rules in a disable block comment into the toggledRules object
+ * under the correct rule name along with the line an column number where the disable block comment
+ * was encountered
+ *
+ * @param {Object} toggledRules - Contains the information about each rule enable
+                                  encountered and and what line/column that block occurred on
+ * @param {Array} rules - An array of rule names
+ * @param {Object} block - The block that is to be disabled
+ */
 var addDisableBlock = function (toggledRules, rules, block) {
   rules.map(function (rule) {
     toggledRules.ruleEnable[rule] = toggledRules.ruleEnable[rule] || [];
@@ -22,16 +54,43 @@ var addDisableBlock = function (toggledRules, rules, block) {
   });
 };
 
+/**
+ * Adds a globally disabled flag to the toggled rules globalEnable property including the line and column
+ * that this comment was encountered on.
+ *
+ * @param {Object} toggledRules - Contains the information about the globally disable comment
+                                  encountered and and what line/column it occurred on
+ * @param {number} line - The line number the disable appeared on
+ * @param {number} column - The column number the disable appeared on
+ */
 var addDisableAll = function (toggledRules, line, column) {
   toggledRules.globalEnable
     .push([false, line, column]);
 };
 
+/**
+ * Adds a globally enabled flag to the toggled rules globalEnable property including the line and column
+ * that this comment was encountered on.
+ *
+ * @param {Object} toggledRules - Contains the information about the globally enable comment
+                                  encountered and and what line/column it occurred on
+ * @param {number} line - The line number the enable appeared on
+ * @param {number} column - The column number the enable appeared on
+ */
 var addEnableAll = function (toggledRules, line, column) {
   toggledRules.globalEnable
     .push([true, line, column]);
 };
 
+/**
+ * Adds a line disabled flag to the ruleEnable property of the toggledRules object for each rule name
+ * encountered in the comment and which line this comment was discovered on / refers to
+ *
+ * @param {Object} toggledRules - Contains the information about the line disable comment encountered, the rules
+ *                              it relates to and which line it was encountered on
+ * @param {Array} rules - An array of rule names to apply
+ * @param {number} line - The line number that this disable should refer to
+ */
 var addDisableLine = function (toggledRules, rules, line) {
   rules.map(function (rule) {
     toggledRules.ruleEnable[rule] = toggledRules.ruleEnable[rule] || [];
@@ -41,6 +100,15 @@ var addDisableLine = function (toggledRules, rules, line) {
   });
 };
 
+/**
+ * This is the sorting function we use to sort the toggle stacks in our getToggledRules method
+ * First sorts by line and then by column if the lines are identical
+ *
+ * @param {Array} toggleRangeA - The first rule to sort
+ * @param {Array} toggleRangeB - The second rule to sort
+ *
+ * @returns {number} A pointer to signify to the sort method how the currently in focus value should be sorted
+ */
 var sortRange = function (toggleRangeA, toggleRangeB) {
   var aLine = toggleRangeA[1],
       aCol = toggleRangeA[2],
@@ -61,6 +129,29 @@ var sortRange = function (toggleRangeA, toggleRangeB) {
   return 0;
 };
 
+/**
+ * Checks if line number A is before line number B, if it's the same then it checks if the column of A
+ * is before the column of B
+ *
+ * @param {number} x - The line number of A
+ * @param {number} y - The column number of A
+ * @param {number} x2 - The line number of B
+ * @param {number} y2 - The column number of B
+ *
+ * @returns {Boolean} Whether the current line/column A is before or the same as B
+ */
+var isBeforeOrSame = function (x, y, x2, y2) {
+  return x < x2 || (x === x2 && y < y2);
+};
+
+/**
+ * Traverses the AST looking for sass-lint disable/enable comments and then building a Object representation
+ * of any it encounters
+ *
+ * @param {Object} ast - Gonzales PE abstract syntax tree
+ *
+ * @returns {Object} The toggledRules object containing all of our rule enable/disable information
+ */
 module.exports.getToggledRules = function (ast) {
   var toggledRules = {
     ruleEnable: {
@@ -118,10 +209,14 @@ module.exports.getToggledRules = function (ast) {
   return toggledRules;
 };
 
-var isBeforeOrSame = function (x, y, x2, y2) {
-  return x < x2 || (x === x2 && y < y2);
-};
-
+/**
+ * Filters our rule results by checking the lint result and it's line/column against our
+ * toggledRules object to see whether we should still be reporting this lint.
+ *
+ * @param {Object} toggledRules - The toggledRules object containing all of our rule enable/disable information
+ *
+ * @returns {Boolean} Whethere the current rule is disabled for this lint report
+ */
 module.exports.isResultEnabled = function (toggledRules) {
   return function (ruleResult) {
     var ruleId = ruleResult.ruleId;