Simplify error parsing by attaching errors to comments

Author: tmcw

bin/documentation.js

@@ -8,6 +8,7 @@ var documentation = require('../'),
   path = require('path'),
   fs = require('fs'),
   vfs = require('vinyl-fs'),
+  formatError = require('../lib/error'),
   loadConfig = require('../lib/load_config.js'),
   args = require('../lib/args.js'),
   argv = args.parse(process.argv.slice(2));
@@ -65,13 +66,15 @@ documentation(inputs, {
   polyglot: argv.polyglot,
   order: config.order || [],
   shallow: argv.shallow
-}, function (err, result, lints) {
+}, function (err, result) {
   if (err) {
     throw err;
   }
 
-  lints.forEach(function (err) {
-    console.error(err);
+  result.forEach(function (comment) {
+    comment.errors.forEach(function (error) {
+      console.error(formatError(comment, error));
+    });
   });
 
   formatter(result, formatterOptions, function (err, output) {

index.js

@@ -52,14 +52,17 @@ module.exports = function (indexes, options, callback) {
   return inputStream.pipe(concat(function (inputs) {
     try {
 
+      var errors = [];
+
       var docs = inputs
         .filter(filterJS)
         .reduce(function (memo, file) {
           return memo.concat(parse(file));
         }, [])
         .map(function (comment) {
+          comment.errors = [];
           // compose nesting & membership to avoid intermediate arrays
-          comment = nestParams(inferMembership(inferKind(inferName(comment))));
+          comment = nestParams(inferMembership(inferKind(inferName(lint(comment)))));
           if (options.github) {
             comment = github(comment);
           }
@@ -68,9 +71,7 @@ module.exports = function (indexes, options, callback) {
         .sort(sort.bind(undefined, options.order))
         .filter(filterAccess.bind(undefined, options.private ? [] : undefined));
 
-      callback(null, docs, docs.reduce(function (memo, comment) {
-        return memo.concat(lint(comment));
-      }, []));
+      callback(null, docs, errors);
     } catch (e) {
       callback(e);
     }

lib/error.js

@@ -6,15 +6,14 @@ var path = require('path');
 /**
  * Format an error message regarding a comment, prefixed with file name and line number.
  *
- * @param {Tag|null} tag location in a javascript file, if any
  * @param {Comment} comment a parsed comment
  * @param {string} error error message a string
  * @param {...*} varags format arguments
  * @returns {undefined} outputs to stderr
  */
-module.exports = function (tag, comment, error) {
+module.exports = function (comment, error) {
   var relativePath = path.relative(process.cwd(), comment.context.file),
-    lineNumber = (tag ? tag.lineNumber : 0) + comment.loc.start.line;
+    lineNumber = comment.loc.start.line;
 
   return format.apply(format, ['%s:%d: ' + error, relativePath, lineNumber]
     .concat(Array.prototype.slice.call(arguments, 3)));

lib/hierarchy.js

@@ -60,9 +60,7 @@ function inferHierarchy(comments) {
     var parent = nameIndex[comment.memberof];
 
     if (!parent) {
-      var err = error(null, comment, 'memberof reference to %s not found', comment.memberof);
-      comment.errors = (comment.errors || []).concat(err);
-      console.error(err);
+      comment.errors.push('memberof reference to ' + comment.memberof + ' not found');
       continue;
     }
 
@@ -73,9 +71,7 @@ function inferHierarchy(comments) {
 
     default:
       if (!comment.scope) {
-        var err2 = error(null, comment, 'found memberof but no @scope, @static, or @instance tag');
-        comment.errors = (comment.errors || []).concat(err2);
-        console.error(err2);
+        comment.errors.push('found memberof but no @scope, @static, or @instance tag');
         continue;
       }
       parent.members[comment.scope].push(comment);

lib/lint.js

@@ -24,7 +24,8 @@ module.exports = function (comment) {
   comment.tags.forEach(function (tag) {
     function nameInvariant(name) {
       if (CANONICAL[name]) {
-        errors.push(error(tag, comment, 'type %s found, %s is standard', name, CANONICAL[name]));
+        comment.errors.push(
+          'type ' + name + ' found, ' + CANONICAL[name] + ' is standard');
       }
     }
 
@@ -48,6 +49,5 @@ module.exports = function (comment) {
       checkCanonical(tag.type);
     }
   });
-  return errors;
+  return comment;
 };
-

lib/nest_params.js

@@ -30,10 +30,8 @@ module.exports = function (comment) {
     if (parts.length > 1) {
       var parent = index[parts[0]];
       if (parent === undefined) {
-        console.error(
-          '@param %s\'s parent %s not found',
-          param.name,
-          parts[0]);
+        result.errors.push(
+          '@param ' + param.name + '\'s parent ' + parts[0] + ' not found');
         result.params.push(param);
         return;
       }

test/lib/hierarchy.js

@@ -94,6 +94,6 @@ test('hierarchy - missing memberof', function (t) {
   });
 
   t.equal(result.length, 1);
-  t.equal(result[0].errors.length, 1);
+  t.equal(result[0].errors[0], 'memberof reference to DoesNotExist not found', 'correct error message');
   t.end();
 });

test/lib/nest_params.js

@@ -53,6 +53,8 @@ test('nestParams - missing parent', function (t) {
     return 0;
   });
   t.equal(result[0].params.length, 1);
+  t.equal(result[0].errors[0], '@param foo.bar\'s parent foo not found',
+    'correct error message');
   t.equal(result[0].params[0].name, 'foo.bar');
   t.end();
 });