Enable jsdoc/require-jsdoc rule, fix all violations (fixes #85).

lib/markdownlint.js

@@ -12,7 +12,13 @@ const cache = require("./cache");
 
 const deprecatedRuleNames = [ "MD002", "MD006" ];
 
-// Validates the list of rules for structure and reuse
+
+/**
+ * Validate the list of rules for structure and reuse.
+ *
+ * @param {Rule[]} ruleList List of rules.
+ * @returns {string} Error message if validation fails.
+ */
 function validateRuleList(ruleList) {
   let result = null;
   if (ruleList.length === rules.length) {
@@ -22,6 +28,7 @@ function validateRuleList(ruleList) {
   const allIds = {};
   ruleList.forEach(function forRule(rule, index) {
     const customIndex = index - rules.length;
+    // eslint-disable-next-line jsdoc/require-jsdoc
     function newError(property) {
       return new Error(
         "Property '" + property + "' of custom rule at index " +
@@ -72,8 +79,14 @@ function validateRuleList(ruleList) {
   return result;
 }
 
-// Class for results with toString for pretty display
+/**
+ * Creates a LintResults instance with toString for pretty display.
+ *
+ * @param {Rule[]} ruleList List of rules.
+ * @returns {LintResults} New LintResults instance.
+ */
 function newResults(ruleList) {
+  // eslint-disable-next-line jsdoc/require-jsdoc
   function Results() {}
   Results.prototype.toString = function toString(useAlias) {
     const that = this;
@@ -123,10 +136,17 @@ function newResults(ruleList) {
     });
     return results.join("\n");
   };
+  // @ts-ignore
   return new Results();
 }
 
-// Remove front matter (if present at beginning of content)
+/**
+ * Remove front matter (if present at beginning of content).
+ *
+ * @param {string} content Markdown content.
+ * @param {RegExp} frontMatter Regular expression to match front matter.
+ * @returns {Object} Trimmed content and front matter lines.
+ */
 function removeFrontMatter(content, frontMatter) {
   let frontMatterLines = [];
   if (frontMatter) {
@@ -147,7 +167,13 @@ function removeFrontMatter(content, frontMatter) {
   };
 }
 
-// Annotate tokens with line/lineNumber
+/**
+ * Annotate tokens with line/lineNumber.
+ *
+ * @param {MarkdownItToken[]} tokens Array of markdown-it tokens.
+ * @param {string[]} lines Lines of Markdown content.
+ * @returns {void}
+ */
 function annotateTokens(tokens, lines) {
   let tbodyMap = null;
   tokens.forEach(function forToken(token) {
@@ -192,7 +218,12 @@ function annotateTokens(tokens, lines) {
   });
 }
 
-// Map rule names/tags to canonical rule name
+/**
+ * Map rule names/tags to canonical rule name.
+ *
+ * @param {Rule[]} ruleList List of rules.
+ * @returns {Object.<string, string[]>} Map of alias to rule name.
+ */
 function mapAliasToRuleNames(ruleList) {
   const aliasToRuleNames = {};
   // const tagToRuleNames = {};
@@ -219,10 +250,19 @@ function mapAliasToRuleNames(ruleList) {
   //   console.log("* **" + tag + "** - " +
   //     aliasToRuleNames[tag.toUpperCase()].join(", "));
   // });
+  // @ts-ignore
   return aliasToRuleNames;
 }
 
-// Apply (and normalize) config
+/**
+ * Apply (and normalize) configuration object.
+ *
+ * @param {Rule[]} ruleList List of rules.
+ * @param {Configuration} config Configuration object.
+ * @param {Object.<string, string[]>} aliasToRuleNames Map of alias to rule
+ * names.
+ * @returns {Configuration} Effective configuration.
+ */
 function getEffectiveConfig(ruleList, config, aliasToRuleNames) {
   const defaultKey = Object.keys(config).filter(
     (key) => key.toUpperCase() === "DEFAULT"
@@ -253,10 +293,25 @@ function getEffectiveConfig(ruleList, config, aliasToRuleNames) {
   return effectiveConfig;
 }
 
-// Create mapping of enabled rules per line
+/**
+ * Create a mapping of enabled rules per line.
+ *
+ * @param {Rule[]} ruleList List of rules.
+ * @param {string[]} lines List of content lines.
+ * @param {string[]} frontMatterLines List of front matter lines.
+ * @param {boolean} noInlineConfig Whether to allow inline configuration.
+ * @param {Configuration} effectiveConfig Effective configuration.
+ * @param {Object.<string, string[]>} aliasToRuleNames Map of alias to rule
+ * names.
+ * @returns {Object.<string, RuleConfiguration>[]} Enabled rules for each line.
+ */
 function getEnabledRulesPerLineNumber(
-  ruleList, lines, frontMatterLines, noInlineConfig,
-  effectiveConfig, aliasToRuleNames) {
+  ruleList,
+  lines,
+  frontMatterLines,
+  noInlineConfig,
+  effectiveConfig,
+  aliasToRuleNames) {
   let enabledRules = {};
   const allRuleNames = [];
   ruleList.forEach((rule) => {
@@ -265,6 +320,7 @@ function getEnabledRulesPerLineNumber(
     enabledRules[ruleName] = !!effectiveConfig[ruleName];
   });
   let capturedRules = enabledRules;
+  // eslint-disable-next-line jsdoc/require-jsdoc
   function forMatch(match, byLine) {
     const action = match[1].toUpperCase();
     if (action === "CAPTURE") {
@@ -312,22 +368,53 @@ function getEnabledRulesPerLineNumber(
   return enabledRulesPerLineNumber;
 }
 
-// Array.sort comparison for objects in errors array
+/**
+ * Compare function for Array.prototype.sort for ascending order of errors.
+ *
+ * @param {LintError} a First error.
+ * @param {LintError} b Second error.
+ * @returns {number} Positive value if a>b, negative value if b<a, 0 otherwise.
+ */
 function lineNumberComparison(a, b) {
   return a.lineNumber - b.lineNumber;
 }
 
-// Function to return true for all inputs
+/**
+ * Filter function to include everything.
+ *
+ * @returns {boolean} True.
+ */
 function filterAllValues() {
   return true;
 }
 
-// Function to return unique values from a sorted errors array
+/**
+ * Function to return unique values from a sorted errors array.
+ *
+ * @param {LintError} value Error instance.
+ * @param {number} index Index in array.
+ * @param {LintError[]} array Array of errors.
+ * @returns {boolean} Filter value.
+ */
 function uniqueFilterForSortedErrors(value, index, array) {
   return (index === 0) || (value.lineNumber > array[index - 1].lineNumber);
 }
 
-// Lints a single string
+/**
+ * Lints a string containing Markdown content.
+ *
+ * @param {Rule[]} ruleList List of rules.
+ * @param {string} name Identifier for the content.
+ * @param {string} content Markdown content
+ * @param {Object} md markdown-it instance.
+ * @param {Configuration} config Configuration object.
+ * @param {RegExp} frontMatter Regular expression for front matter.
+ * @param {boolean} handleRuleFailures Whether to handle exceptions in rules.
+ * @param {boolean} noInlineConfig Whether to allow inline configuration.
+ * @param {number} resultVersion Version of the LintResults object to return.
+ * @param {Function} callback Callback (err, result) function.
+ * @returns {void}
+ */
 function lintContent(
   ruleList,
   name,
@@ -367,16 +454,19 @@ function lintContent(
   cache.flattenedLists(helpers.flattenLists(params));
   // Function to run for each rule
   const result = (resultVersion === 0) ? {} : [];
+  // eslint-disable-next-line jsdoc/require-jsdoc
   function forRule(rule) {
     // Configure rule
     const ruleNameFriendly = rule.names[0];
     const ruleName = ruleNameFriendly.toUpperCase();
     params.config = effectiveConfig[ruleName];
+    // eslint-disable-next-line jsdoc/require-jsdoc
     function throwError(property) {
       throw new Error(
         "Property '" + property + "' of onError parameter is incorrect.");
     }
     const errors = [];
+    // eslint-disable-next-line jsdoc/require-jsdoc
     function onError(errorInfo) {
       if (!errorInfo ||
         !helpers.isNumber(errorInfo.lineNumber) ||
@@ -518,7 +608,21 @@ function lintContent(
   return callback(null, result);
 }
 
-// Lints a single file
+/**
+ * Lints a file containing Markdown content.
+ *
+ * @param {Rule[]} ruleList List of rules.
+ * @param {string} file Path of file to lint.
+ * @param {Object} md markdown-it instance.
+ * @param {Configuration} config Configuration object.
+ * @param {RegExp} frontMatter Regular expression for front matter.
+ * @param {boolean} handleRuleFailures Whether to handle exceptions in rules.
+ * @param {boolean} noInlineConfig Whether to allow inline configuration.
+ * @param {number} resultVersion Version of the LintResults object to return.
+ * @param {boolean} synchronous Whether to execute synchronously.
+ * @param {Function} callback Callback (err, result) function.
+ * @returns {void}
+ */
 function lintFile(
   ruleList,
   file,
@@ -530,6 +634,7 @@ function lintFile(
   resultVersion,
   synchronous,
   callback) {
+  // eslint-disable-next-line jsdoc/require-jsdoc
   function lintContentWrapper(err, content) {
     if (err) {
       return callback(err);
@@ -545,7 +650,14 @@ function lintFile(
   }
 }
 
-// Lints files and strings
+/**
+ * Lint files and strings specified in the Options object.
+ *
+ * @param {Options} options Options object.
+ * @param {boolean} synchronous Whether to execute synchronously.
+ * @param {Function} callback Callback (err, result) function.
+ * @returns {void}
+ */
 function lintInput(options, synchronous, callback) {
   // Normalize inputs
   options = options || {};
@@ -579,9 +691,11 @@ function lintInput(options, synchronous, callback) {
   const results = newResults(ruleList);
   // Helper to lint the next string or file
   /* eslint-disable consistent-return */
+  // eslint-disable-next-line jsdoc/require-jsdoc
   function lintNextItem() {
     let iterating = true;
     let item = null;
+    // eslint-disable-next-line jsdoc/require-jsdoc
     function lintNextItemCallback(err, result) {
       if (err) {
         iterating = false;
@@ -652,7 +766,14 @@ function markdownlintSync(options) {
   return results;
 }
 
-// Parses the content of a configuration file
+/**
+ * Parse the content of a configuration file.
+ *
+ * @param {string} name Name of the configuration file.
+ * @param {string} content Configuration content.
+ * @param {ConfigurationParser[]} parsers Parsing function(s).
+ * @returns {Object} Configuration object and error message.
+ */
 function parseConfiguration(name, content, parsers) {
   let config = null;
   let message = "";
@@ -698,6 +819,7 @@ function readConfig(file, parsers, callback) {
       return callback(err);
     }
     // Try to parse file
+    // @ts-ignore
     const { config, message } = parseConfiguration(file, content, parsers);
     if (!config) {
       return callback(new Error(message));