fix(valid-types): allow more namepath-defining tags by default

Some namepath-defining tags allow the defining of a name elsewhere in the block, so don't automatically enforce rule against these tags

Author: brettz9

.README/rules/valid-types.md

@@ -4,16 +4,25 @@ Requires all types to be valid JSDoc or Closure compiler types without syntax er
 
 Also impacts behaviors on namepath (or event)-defining and pointing tags:
 
-1. Name(path)-defining tags: `@class`, `@constructor`, `@constant`, `@const`, `@external`, `@host`, `@function`, `@func`, `@method`, `@interface`, `@member`, `@var`, `@mixin`, `@name`, `@namespace`, `@typedef`
-1. Name(path)-pointing tags: `@alias`, `@augments`, `@extends`, `@lends`, `@memberof`, `@memberof!`, `@mixes`, `@this`
-1. Name(path)-defining tags (which may have value without namepath): `@callback`, `@event`
-1. Name(path)-pointing tags (which may have value without namepath): `@listens`, `@fires`, `@emits`
+1. Name(path)-defining tags requiring namepath: `@external`, `@host`, `@name`, `@typedef`
+1. Name(path)-defining tags (which may have value without namepath or their
+    namepath can be expressed elsewhere on the block): `@event`, `@callback`,
+    `@class`, `@constructor`, `@constant`, `@const`,
+    `@function`, `@func`, `@method`, `@interface`, `@member`, `@var`,
+    `@mixin`, `@namespace`
+1. Name(path)-pointing tags requiring namepath: `@alias`, `@augments`, `@extends`, `@lends`, `@memberof`, `@memberof!`, `@mixes`, `@this`
+1. Name(path)-pointing tags (which may have value without namepath or their
+    namepath can be expressed elsewhere on the block): `@listens`, `@fires`,
+    `@emits`
 1. Name(path)-pointing tags (multiple names in one): `@borrows`
 
 ...with the following applying to the above sets:
 
 - Expect tags in set 1-4 to have a valid namepath if present
-- Prevent sets 3-4 from being empty by setting `allowEmptyNamepaths` to `false` as these tags might have some indicative value without a path (but sets 1-2 will always fail if empty)
+- Prevent sets 2 and 4 from being empty by setting `allowEmptyNamepaths` to
+  `false` as these tags might have some indicative value without a path
+  or may allow a name expressed elsewhere on the block (but sets 1 and 3 will
+  always fail if empty)
 - For the special case of set 5, i.e., `@borrows <that namepath> as <this namepath>`, check that both namepaths are present and valid and ensure there is an `as ` between them.
 
 |||

src/iterateJsdoc.js

@@ -158,10 +158,8 @@ const curryUtils = (
   };
 
   utils.passesEmptyNamepathCheck = (tag) => {
-    return !tag.name && allowEmptyNamepaths && [
-      // These may serve some minor purpose when empty
-      'callback', 'event', 'listens', 'fires', 'emits'
-    ].includes(tag.tag);
+    return !tag.name && allowEmptyNamepaths &&
+      jsdocUtils.isPotentiallyEmptyNamepathTag(tag.tag);
   };
 
   utils.hasDefinedTypeReturnTag = (tag) => {

src/jsdocUtils.js

@@ -119,30 +119,32 @@ const hasDefinedTypeReturnTag = (tag) => {
 
 const namepathDefiningTags = [
   // NOT USEFUL WITHOUT NAMEPATH
-  'class', 'constructor',
-  'constant', 'const',
   'external', 'host',
-  'function', 'func', 'method',
-  'interface',
-  'member', 'var',
-  'mixin',
   'name',
-  'namespace',
   'typedef',
 
   // MAY BE USEFUL WITHOUT NAMEPATH
+  'event',
+
+  // MAY BE USEFUL WITHOUT NAMEPATH (OR
+  //  BLOCK CAN USE NAMEPATH FROM ELSEWHERE)
+  'class', 'constructor',
+  'constant', 'const',
   'callback',
-  'event'
+  'function', 'func', 'method',
+  'interface',
+  'member', 'var',
+  'mixin',
+  'namespace'
 ];
 
 const namepathPointingTags = [
   // NOT USEFUL WITHOUT NAMEPATH
   'alias',
-  'augments',
+  'augments', 'extends',
 
   // `borrows` has a different format, however, so needs special parsing
   'borrows',
-  'extends',
   'lends',
   'memberof',
   'memberof!',
@@ -169,6 +171,25 @@ const isNamepathTag = (tagName, checkSeesForNamepaths) => {
     isNamepathPointingTag(tagName, checkSeesForNamepaths);
 };
 
+const potentiallyEmptyNamepathTags = [
+  // These may serve some minor purpose when empty or
+  //  their namepath can be expressed elsewhere on the block
+  'event',
+  'callback',
+  'class', 'constructor',
+  'constant', 'const',
+  'function', 'func', 'method',
+  'interface',
+  'member', 'var',
+  'mixin',
+  'namespace',
+  'listens', 'fires', 'emits'
+];
+
+const isPotentiallyEmptyNamepathTag = (tag) => {
+  return potentiallyEmptyNamepathTags.includes(tag);
+};
+
 let tagsWithTypes = [
   'class',
   'constant',
@@ -442,6 +463,7 @@ export default {
   hasTag,
   isNamepathDefiningTag,
   isNamepathTag,
+  isPotentiallyEmptyNamepathTag,
   isTagWithType,
   isValidTag
 };

test/rules/assertions/validTypes.js

@@ -165,7 +165,7 @@ export default {
     {
       code: `
           /**
-           * @alias module:svgcanvas.SvgCanvas#event:ext_langReady
+           * @alias module:namespace.SomeClass#event:ext_anevent
            */
           function quux() {
 
@@ -182,13 +182,34 @@ export default {
           }
       `
     },
+    {
+      code: `
+          /**
+           * @class
+           */
+          function quux() {
+
+          }
+      `
+    },
     {
       code: `
           /**
            * @see {@link foo}
            */
           function quux() {
 
+          }
+      `
+    },
+    {
+      code: `
+          /**
+           *
+           * @fires {module:namespace.SomeClass#event:ext_anevent}
+           */
+          function quux() {
+
           }
       `
     }