Merge pull request #308 from interfaced/feature/add-more-type-checks-…

…to-valid-types feat(`valid-types`): add more type checks
gajus · Sep 1, 2019 · 12ae7c6 · 12ae7c6
2 parents 112f244 + 902fac0
commit 12ae7c6
Show file tree

Hide file tree

Showing 7 changed files with 381 additions and 130 deletions.
diff --git a/README.md b/README.md
@@ -7362,39 +7362,39 @@ function quux() {
 function quux() {
 
 }
-// Message: Syntax error in type: module:namespace.SomeClass<~
+// Message: Syntax error in namepath: module:namespace.SomeClass<~
 
 /**
  * @memberof module:namespace.SomeClass~<
  */
 function quux() {
 
 }
-// Message: Syntax error in type: module:namespace.SomeClass~<
+// Message: Syntax error in namepath: module:namespace.SomeClass~<
 
 /**
  * @borrows foo% as bar
  */
 function quux() {
 
 }
-// Message: Syntax error in type: foo%
+// Message: Syntax error in namepath: foo%
 
 /**
  * @borrows #foo as bar
  */
 function quux() {
 
 }
-// Message: Syntax error in type: #foo
+// Message: Syntax error in namepath: #foo
 
 /**
  * @borrows foo as bar%
  */
 function quux() {
 
 }
-// Message: Syntax error in type: bar%
+// Message: Syntax error in namepath: bar%
 
 /**
  * @borrows foo
@@ -7411,7 +7411,7 @@ function quux() {
 
 }
 // Options: [{"checkSeesForNamepaths":true}]
-// Message: Syntax error in type: foo%
+// Message: Syntax error in namepath: foo%
 
 /** */
 function foo() {}
@@ -7424,15 +7424,15 @@ function foo() {}
 function quux() {
 
 }
-// Message: Syntax error in type: module:abc#event:foo-bar
+// Message: Syntax error in namepath: module:abc#event:foo-bar
 
 /**
  * @mixes module:namespace.SomeClass~
  */
 function quux() {
 
 }
-// Message: Syntax error in type: module:namespace.SomeClass~
+// Message: Syntax error in namepath: module:namespace.SomeClass~
 
 /**
  * @callback
@@ -7441,7 +7441,35 @@ function quux() {
 
 }
 // Options: [{"allowEmptyNamepaths":false}]
-// Message: Syntax error in type: 
+// Message: Tag @callback must have a namepath
+
+/**
+ * @constant {str%ng}
+ */
+ const FOO = 'foo';
+// Message: Syntax error in type: str%ng
+
+/**
+ * @typedef {str%ng} UserString
+ */
+// Message: Syntax error in type: str%ng
+
+/**
+ * @typedef {string} UserStr%ng
+ */
+// Message: Syntax error in namepath: UserStr%ng
+
+/**
+ * @extends
+ */
+ class Bar {};
+// Message: Tag @extends must have either a type or namepath
+
+/**
+ * @type
+ */
+ let foo;
+// Message: Tag @type must have a type
 ````
 
 The following patterns are not considered problems:
@@ -7496,12 +7524,20 @@ function quux() {
 
 }
 
+/**
+ * @callback foo
+ */
+function quux() {
+
+}
+
 /**
  * @callback
  */
 function quux() {
 
 }
+// Options: [{"allowEmptyNamepaths":true}]
 
 /**
  * @class
@@ -7516,6 +7552,7 @@ function quux() {
 function quux() {
 
 }
+// Options: [{"checkSeesForNamepaths":true}]
 
 /**
  *
@@ -7545,6 +7582,35 @@ function quux() {
 function quux() {
 
 }
+
+/**
+ * @constant {string}
+ */
+ const FOO = 'foo';
+
+/**
+ * @constant {string} FOO
+ */
+ const FOO = 'foo';
+
+/**
+ * @extends Foo
+ */
+ class Bar {};
+
+/**
+ * @extends {Foo<String>}
+ */
+ class Bar {};
+
+/**
+ * @typedef {number|string} UserDefinedType
+ */
+
+/**
+ * @typedef {number|string}
+ */
+let UserDefinedGCCType;
 ````
 
 
diff --git a/src/iterateJsdoc.js b/src/iterateJsdoc.js
@@ -11,19 +11,31 @@ import getJSDocComment from './eslint/getJSDocComment';
  * @returns {object}
  */
 const parseComment = (commentNode, indent, trim = true) => {
+  const skipSeeLink = (parser) => {
+    return (str, data) => {
+      if (data.tag === 'see' && str.match(/{@link.+?}/)) {
+        return null;
+      }
+
+      return parser(str, data);
+    };
+  };
+
   // Preserve JSDoc block start/end indentation.
   return commentParser(`${indent}/*${commentNode.value}${indent}*/`, {
     // @see https://github.com/yavorskiy/comment-parser/issues/21
     parsers: [
       commentParser.PARSERS.parse_tag,
-      commentParser.PARSERS.parse_type,
-      (str, data) => {
-        if (['example', 'return', 'returns', 'throws', 'exception'].includes(data.tag)) {
-          return null;
-        }
+      skipSeeLink(commentParser.PARSERS.parse_type),
+      skipSeeLink(
+        (str, data) => {
+          if (['example', 'return', 'returns', 'throws', 'exception'].includes(data.tag)) {
+            return null;
+          }
 
-        return commentParser.PARSERS.parse_name(str, data);
-      },
+          return commentParser.PARSERS.parse_name(str, data);
+        },
+      ),
       trim ?
         commentParser.PARSERS.parse_description :
 
@@ -181,20 +193,32 @@ const getUtils = (
     return false;
   };
 
-  utils.isNamepathDefiningTag = (tagName) => {
-    return jsdocUtils.isNamepathDefiningTag(tagName);
+  utils.tagMustHaveEitherTypeOrNamepath = (tagName) => {
+    return jsdocUtils.tagMustHaveEitherTypeOrNamepath(tagName);
+  };
+
+  utils.tagMightHaveEitherTypeOrNamepath = (tagName) => {
+    return jsdocUtils.tagMightHaveEitherTypeOrNamepath(tagName);
   };
-  utils.isNamepathTag = (tagName, checkSeesForNamepaths) => {
-    return jsdocUtils.isNamepathTag(tagName, checkSeesForNamepaths);
+
+  utils.tagMustHaveNamepath = (tagName) => {
+    return jsdocUtils.tagMustHaveNamepath(tagName);
   };
 
-  utils.isTagWithType = (tagName) => {
-    return jsdocUtils.isTagWithType(tagName);
+  utils.tagMightHaveNamepath = (tagName) => {
+    return jsdocUtils.tagMightHaveNamepath(tagName);
   };
 
-  utils.passesEmptyNamepathCheck = (tag, allowEmptyNamepaths) => {
-    return !tag.name && allowEmptyNamepaths &&
-      jsdocUtils.isPotentiallyEmptyNamepathTag(tag.tag);
+  utils.tagMustHaveType = (tagName) => {
+    return jsdocUtils.tagMustHaveType(tagName);
+  };
+
+  utils.tagMightHaveType = (tagName) => {
+    return jsdocUtils.tagMightHaveType(tagName);
+  };
+
+  utils.isNamepathDefiningTag = (tagName) => {
+    return jsdocUtils.isNamepathDefiningTag(tagName);
   };
 
   utils.hasDefinedTypeReturnTag = (tag) => {