Document public API, comment framework code.

lib/markdownlint.js

@@ -5,6 +5,7 @@ var md = require("markdown-it")();
 var rules = require("./rules");
 var shared = require("./shared");
 
+// Mapping from rule name to description
 var ruleToDescription = {};
 rules.forEach(function forRule(rule) {
   ruleToDescription[rule.name] = rule.desc;
@@ -12,6 +13,7 @@ rules.forEach(function forRule(rule) {
   // console.log("* " + rule.name + " - " + rule.desc);
 });
 
+// Class for results with toString for pretty display
 function Results() { }
 Results.prototype.toString = function resultsToString() {
   var self = this;
@@ -31,40 +33,48 @@ Results.prototype.toString = function resultsToString() {
   return results.join("\n");
 };
 
+// Array.sort comparison for number objects
 function numberComparison(a, b) {
   return a - b;
 }
 
+// Function to return unique values from a sorted array
 function uniqueFilterForSorted(value, index, array) {
   return (index === 0) || (value > array[index - 1]);
 }
 
+// Lints a single file
 function lintFile(file, config, callback) {
-  fs.readFile(file, { "encoding": "utf8" }, function readFile(err, contents) {
+  fs.readFile(file, shared.utf8Encoding, function readFile(err, contents) {
     if (err) {
       callback(err);
     } else {
+      // Parse file into tokens and lines
       var tokens = md.parse(contents, {});
       var lines = contents.split(shared.newLineRe);
+      // Annotate tokens with line/lineNumber
       tokens.forEach(function forToken(token) {
         if (token.lines) {
           token.line = lines[token.lines[0]];
           token.lineNumber = token.lines[0] + 1;
         }
       });
+      // Create parameters for rules
       var params = {
         "tokens": tokens,
         "lines": lines
       };
       var result = {};
-      var configDefault = config.default;
-      var defaultRule = (configDefault !== undefined) && !!configDefault;
+      var defaultRule = (config.default !== undefined) && !!config.default;
+      // Run each rule
       rules.forEach(function forRule(rule) {
         var ruleConfig = config[rule.name];
         if (ruleConfig || (defaultRule && (ruleConfig === undefined))) {
+          // Pass rule-specific options
           params.options = (ruleConfig instanceof Object) ? ruleConfig : {};
           var errors = [];
           rule.func(params, errors);
+          // Record any errors
           if (errors.length) {
             errors.sort(numberComparison);
             result[rule.name] = errors.filter(uniqueFilterForSorted);
@@ -76,12 +86,21 @@ function lintFile(file, config, callback) {
   });
 }
 
+/**
+ * Lint specified Markdown files according to configurable rules.
+ *
+ * @param {Object} options Configuration options.
+ * @param {Function} callback Callback (err, results) function.
+ * @returns {void}
+ */
 module.exports = function markdownlint(options, callback) {
+  // Normalize inputs
   options = options || {};
   callback = callback || function noop() {};
   var files = (options.files || []).slice();
   var config = options.config || { "default": true };
   var results = new Results();
+  // Lint each input file
   function lintFiles() {
     var file = files.shift();
     if (file) {
@@ -89,6 +108,7 @@ module.exports = function markdownlint(options, callback) {
         if (err) {
           callback(err);
         } else {
+          // Record errors and lint next file
           results[file] = result;
           lintFiles();
         }