fix: Report nesting errors instead of throwing them as errors

Check on parent element: foo.bar sub-parametr should be documeted with parent. Fixed #832 issue
documentationjs · Jul 7, 2017 · ea69608 · ea69608
1 parent 15239d1
commit ea69608
Show file tree

Hide file tree

Showing 4 changed files with 31 additions and 17 deletions.
diff --git a/__tests__/lib/lint.js b/__tests__/lib/lint.js
@@ -28,6 +28,14 @@ test('lintComments', function() {
     { message: 'Missing or invalid tag name' }
   ]);
 
+  expect(
+    evaluate(function() {
+      /**
+      * @param {Object} foo.bar
+      */
+    }).errors
+  ).toEqual([{ commentLineNumber: 1, message: 'Parent of foo.bar not found' }]);
+
   expect(
     evaluate(function() {
       /**

diff --git a/declarations/comment.js b/declarations/comment.js
@@ -71,7 +71,6 @@ type Comment = {
   tags: Array<CommentTag>,
 
   augments: Array<CommentTag>,
-  errors: Array<CommentExample>,
   examples: Array<CommentExample>,
   params: Array<CommentTag>,
   properties: Array<CommentTag>,

diff --git a/src/lint.js b/src/lint.js
@@ -4,6 +4,7 @@ var VFile = require('vfile');
 import { walk } from './walk';
 import vfileSort from 'vfile-sort';
 import reporter from 'vfile-reporter';
+import nest from './nest';
 
 var CANONICAL = {
   String: 'string',
@@ -27,11 +28,8 @@ function lintComments(comment: Comment) {
     function nameInvariant(name) {
       if (name && typeof CANONICAL[name] === 'string') {
         comment.errors.push({
-          message: 'type ' +
-            name +
-            ' found, ' +
-            CANONICAL[name] +
-            ' is standard',
+          message:
+            'type ' + name + ' found, ' + CANONICAL[name] + ' is standard',
           commentLineNumber: tag.lineNumber
         });
       }
@@ -60,6 +58,8 @@ function lintComments(comment: Comment) {
       checkCanonical(tag.type);
     }
   });
+  nest(comment);
+
   return comment;
 }
 

diff --git a/src/nest.js b/src/nest.js
@@ -33,7 +33,8 @@ var tagDepth = tag => tag.name.split(PATH_SPLIT).length;
  * @returns {Object} nested comment
  */
 var nestTag = (
-  tags: Array<CommentTag>
+  tags: Array<CommentTag>,
+  errors: Array<CommentError>
   // Use lodash here both for brevity and also because, unlike JavaScript's
   // sort, it's stable.
 ) =>
@@ -59,16 +60,22 @@ var nestTag = (
 
           if (!child) {
             if (tag.name.match(/^(\$\d+)/)) {
-              throw new Error(
-                `Parent of ${tag.name} not found. To document a destructuring\n` +
+              errors.push({
+                message:
+                  `Parent of ${tag.name} not found. To document a destructuring\n` +
                   `type, add a @param tag in its position to specify the name of the\n` +
-                  `destructured parameter`
-              );
+                  `destructured parameter`,
+                commentLineNumber: tag.lineNumber
+              });
+            } else {
+              errors.push({
+                message: `Parent of ${tag.name} not found`,
+                commentLineNumber: tag.lineNumber
+              });
             }
-            throw new Error(`Parent of ${tag.name} not found`);
+          } else {
+            insertTag(child, parts.slice(1));
           }
-
-          insertTag(child, parts.slice(1));
         }
       }
 
@@ -91,9 +98,9 @@ var nestTag = (
  * @return {Object} nested comment
  */
 var nest = (comment: Comment) =>
-  _.assign(comment, {
-    params: nestTag(comment.params),
-    properties: nestTag(comment.properties)
+  Object.assign(comment, {
+    params: nestTag(comment.params, comment.errors),
+    properties: nestTag(comment.properties, comment.errors)
   });
 
 module.exports = nest;