Include file name and line number in error messages (fixes #87)

Author: jfirebaugh

lib/error.js

@@ -0,0 +1,16 @@
+'use strict';
+
+var format = require('util').format;
+var path = require('path');
+
+/**
+ * Format an error message regarding a comment, prefixed with file name and line number.
+ *
+ * @param comment
+ * @param error
+ */
+module.exports = function(comment, error) {
+  var relativePath = path.relative(process.cwd(), comment.context.file);
+  return format.apply(format, ['%s:%d: ' + error, relativePath, comment.context.loc.start.line]
+    .concat(Array.prototype.slice.call(arguments, 2)));
+};

streams/hierarchy.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var through = require('through');
+var error = require('../lib/error');
 
 /**
  * Infer a hierarchy of documentation from a stream of documentation
@@ -55,10 +56,10 @@ function inferHierarchy(comments) {
           // as members of other docs.
           comments.splice(i, 1);
         } else {
-          console.error('found memberof but no @scope, @static, or @instance tag');
+          console.error(error(comments[i], 'found memberof but no @scope, @static, or @instance tag'));
         }
       } else {
-        console.error('memberof reference to %s not found', comments[i].memberof);
+        console.error(error(comments[i], 'memberof reference to %s not found', comments[i].memberof));
       }
     }
   }

streams/lint.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var through = require('through');
+var error = require('../lib/error');
 
 var CANON = [
   'string',
@@ -21,28 +22,6 @@ var CANONICAL = CANON.reduce(function (memo, name) {
   memo[name] = true; return memo;
 }, {});
 
-function nameInvariant(name) {
-  if (CANONICAL_LOWER[name.toLowerCase()] &&
-      !CANONICAL[name]) {
-    console.log('type %s found, %s is standard',
-      name, CANONICAL_LOWER[name.toLowerCase()]);
-  }
-}
-
-function checkCanonical(type) {
-  if (!type) return;
-  if (type.type === 'NameExpression') {
-    nameInvariant(type.name);
-  } else if (type.type === 'UnionType') {
-    type.elements.forEach(checkCanonical);
-  } else if (type.type === 'OptionalType') {
-    checkCanonical(type.expression);
-  } else if (type.type === 'TypeApplication') {
-    checkCanonical(type.expression);
-    type.applications.map(checkCanonical);
-  }
-}
-
 /**
  * Create a transform stream that passively lints and checks documentation data.
  *
@@ -52,6 +31,27 @@ function checkCanonical(type) {
 module.exports = function () {
 
   return through(function (comment) {
+    function nameInvariant(name) {
+      if (CANONICAL_LOWER[name.toLowerCase()] &&
+        !CANONICAL[name]) {
+        console.log(error(comment, 'type %s found, %s is standard',
+          name, CANONICAL_LOWER[name.toLowerCase()]));
+      }
+    }
+
+    function checkCanonical(type) {
+      if (!type) return;
+      if (type.type === 'NameExpression') {
+        nameInvariant(type.name);
+      } else if (type.type === 'UnionType') {
+        type.elements.forEach(checkCanonical);
+      } else if (type.type === 'OptionalType') {
+        checkCanonical(type.expression);
+      } else if (type.type === 'TypeApplication') {
+        checkCanonical(type.expression);
+        type.applications.map(checkCanonical);
+      }
+    }
 
     comment.tags.forEach(function (tag) {
       if (tag.title === 'param' && tag.type) {

test/lib/error.js

@@ -0,0 +1,29 @@
+'use strict';
+
+var test = require('prova'),
+  util = require('util'),
+  path = require('path'),
+  error = require('../../lib/error');
+
+test('error', function (t) {
+  var comment = {
+    context: {
+      file: path.join(process.cwd(), 'file.js'),
+      loc: {
+        start: {
+          line: 1,
+          column: 2
+        },
+        end: {
+          line: 3,
+          column: 4
+        }
+      }
+    }
+  };
+
+  t.deepEqual(error(comment, 'test'), 'file.js:1: test');
+  t.deepEqual(error(comment, '%s', 'test'), 'file.js:1: test');
+
+  t.end();
+});