Refactor utils naming

Author: l1bbcsg

src/iterateJsdoc.js

@@ -18,7 +18,7 @@ const parseComment = (commentNode, indent, trim = true) => {
       }
 
       return parser(str, data);
-    }
+    };
   };
 
   // Preserve JSDoc block start/end indentation.
@@ -193,27 +193,32 @@ const getUtils = (
     return false;
   };
 
-  utils.isNamepathDefiningTag = (tagName) => {
-    return jsdocUtils.isNamepathDefiningTag(tagName);
+  utils.tagMustHaveEitherTypeOrNamepath = (tagName) => {
+    return jsdocUtils.tagMustHaveEitherTypeOrNamepath(tagName);
   };
-  utils.isNamepathTag = (tagName, checkSeesForNamepaths) => {
-    return jsdocUtils.isNamepathTag(tagName, checkSeesForNamepaths);
+
+  utils.tagMightHaveEitherTypeOrNamepath = (tagName) => {
+    return jsdocUtils.tagMightHaveEitherTypeOrNamepath(tagName);
   };
 
-  utils.isTagWithType = (tagName) => {
-    return jsdocUtils.isTagWithType(tagName);
+  utils.tagMustHaveNamepath = (tagName) => {
+    return jsdocUtils.tagMustHaveNamepath(tagName);
   };
-  utils.isPotentiallyEmptyTypeTag = (tagName) => {
-    return jsdocUtils.isPotentiallyEmptyTypeTag(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.isTagWithMandatoryNamepathOrType = (tagName) => {
-    return jsdocUtils.isTagWithMandatoryNamepathOrType(tagName);
+  utils.tagMightHaveType = (tagName) => {
+    return jsdocUtils.tagMightHaveType(tagName);
+  };
+
+  utils.isNamepathDefiningTag = (tagName) => {
+    return jsdocUtils.isNamepathDefiningTag(tagName);
   };
 
   utils.hasDefinedTypeReturnTag = (tag) => {

src/jsdocUtils.js

@@ -126,17 +126,45 @@ const hasDefinedTypeReturnTag = (tag) => {
   return true;
 };
 
+const tagsWithOptionalType = [
+  'augments', 'extends',
+  'class', 'constructor',
+  'constant', 'const',
+  'enum',
+  'implements',
+  'member', 'var',
+  'module',
+  'namespace',
+  'param', 'arg', 'argument',
+  'property', 'prop',
+  'returns', 'return',
+  'throws', 'exception',
+  'type',
+  'typedef',
+  'yields', 'yield',
+
+  // GCC specific
+  'package',
+  'private',
+  'protected',
+  'public',
+  'static',
+];
+
+const tagsWithMandatoryType = [
+  'enum',
+  'implements',
+  'member', 'var',
+  'module',
+  'type',
+  'typedef',
+];
+
 const namepathDefiningTags = [
-  // NOT USEFUL WITHOUT NAMEPATH
   'external', 'host',
   'name',
   'typedef',
-
-  // MAY BE USEFUL WITHOUT NAMEPATH
   'event',
-
-  // MAY BE USEFUL WITHOUT NAMEPATH (OR
-  //  BLOCK CAN USE NAMEPATH FROM ELSEWHERE)
   'class', 'constructor',
   'constant', 'const',
   'callback',
@@ -147,126 +175,68 @@ const namepathDefiningTags = [
   'namespace',
 ];
 
-const namepathPointingTags = [
-  // NOT USEFUL WITHOUT NAMEPATH
+const tagsWithOptionalNamepath = [
+  ...namepathDefiningTags,
   'alias',
   'augments', 'extends',
 
   // `borrows` has a different format, however, so needs special parsing
   'borrows',
+  'emits', 'fires',
   'lends',
-  'memberof',
-  'memberof!',
+  'listens',
+  'memberof', 'memberof!',
   'mixes',
+  'see',
   'this',
-
-  // MAY BE USEFUL WITHOUT NAMEPATH
-  'emits',
-  'fires',
-  'listens',
 ];
 
-const isNamepathDefiningTag = (tagName) => {
-  return namepathDefiningTags.includes(tagName);
-};
-
-const isNamepathPointingTag = (tagName, checkSeesForNamepaths) => {
-  return namepathPointingTags.includes(tagName) ||
-    tagName === 'see' && checkSeesForNamepaths;
-};
-
-const isNamepathTag = (tagName, checkSeesForNamepaths) => {
-  return isNamepathDefiningTag(tagName) ||
-    isNamepathPointingTag(tagName, checkSeesForNamepaths);
-};
-
-const potentiallyEmptyNamepathTags = [
-  // These may serve some minor purpose when empty or
-  //  their namepath can be expressed elsewhere on the block
-  'event',
+const tagsWithMandatoryNamepath = [
   'callback',
-  'class', 'constructor',
-  'extends', 'augments',
-  'constant', 'const',
-  'function', 'func', 'method',
-  'interface',
-  'member', 'var',
-  'mixin',
-  'namespace',
-  'listens', 'fires', 'emits',
-  'see',
-
-  // GCC syntax allows typedef to be named through variable declaration rather than jsdoc name
+  'external', 'host',
+  'name',
   'typedef',
 ];
 
-const isPotentiallyEmptyNamepathTag = (tag) => {
-  return potentiallyEmptyNamepathTags.includes(tag);
-};
-
-let tagsWithTypes = [
+const tagsWithMandatoryEitherTypeOrNamepath = [
+  'alias',
   'augments', 'extends',
-  'class',
-  'constant',
-  'enum',
-  'implements',
-  'member',
-  'module',
-  'namespace',
-  'param',
-  'property',
-  'returns',
-  'throws',
-  'type',
+  'borrows',
+  'external', 'host',
+  'lends',
+  'memberof', 'memberof!',
+  'mixes',
+  'name',
+  'this',
   'typedef',
-  'yields',
 ];
 
-const closureTagsWithTypes = [
-  'package', 'private', 'protected', 'public', 'static',
-];
+const isNamepathDefiningTag = (tagName) => {
+  return namepathDefiningTags.includes(tagName);
+};
 
-const tagsWithTypesAliases = [
-  'constructor',
-  'const',
-  'var',
-  'arg',
-  'argument',
-  'prop',
-  'return',
-  'exception',
-  'yield',
-];
+const tagMightHaveType = (tag) => {
+  return tagsWithOptionalType.includes(tag);
+};
 
-tagsWithTypes = tagsWithTypes.concat(tagsWithTypesAliases, closureTagsWithTypes);
+const tagMustHaveType = (tag) => {
+  return tagsWithMandatoryType.includes(tag);
+};
 
-const potentiallyEmptyTypeTags = [
-  'class', 'constructor',
-  'constant', 'const',
-  'extends', 'augments',
-  'namespace',
-  'param', 'arg',
-  'return', 'returns',
-  'throws', 'exception',
-  'yields', 'yield',
-  'package', 'private', 'protected', 'public', 'static',
-];
+const tagMightHaveNamepath = (tag) => {
+  return tagsWithOptionalNamepath.includes(tag);
+};
 
-const isPotentiallyEmptyTypeTag = (tag) => {
-  return potentiallyEmptyTypeTags.includes(tag);
+const tagMustHaveNamepath = (tag) => {
+  return tagsWithMandatoryNamepath.includes(tag);
 };
 
-const isTagWithType = (tagName) => {
-  return tagsWithTypes.includes(tagName);
+const tagMightHaveEitherTypeOrNamepath = (tag) => {
+  return tagMightHaveType(tag) || tagMightHaveNamepath(tag);
 };
 
-const tagsWithMandatoryNamepathOrType = [
-  'augments', 'extends',
-  'param', 'arg',
-  'typedef',
-];
-const isTagWithMandatoryNamepathOrType = (tagName) => {
-  return tagsWithMandatoryNamepathOrType.includes(tagName);
+const tagMustHaveEitherTypeOrNamepath = (tag) => {
+  return tagsWithMandatoryEitherTypeOrNamepath.includes(tag);
 };
 
 /**
@@ -451,11 +421,12 @@ export default {
   hasReturnValue,
   hasTag,
   isNamepathDefiningTag,
-  isNamepathTag,
-  isPotentiallyEmptyNamepathTag,
-  isPotentiallyEmptyTypeTag,
-  isTagWithMandatoryNamepathOrType,
-  isTagWithType,
   isValidTag,
   parseClosureTemplateTag,
+  tagMightHaveEitherTypeOrNamepath,
+  tagMightHaveNamepath,
+  tagMightHaveType,
+  tagMustHaveEitherTypeOrNamepath,
+  tagMustHaveNamepath,
+  tagMustHaveType,
 };

src/rules/checkTypes.js

@@ -26,7 +26,7 @@ export default iterateJsdoc(({
   context,
 }) => {
   const jsdocTags = utils.filterTags((tag) => {
-    return utils.isTagWithType(tag.tag);
+    return utils.tagMightHaveType(tag.tag);
   });
 
   const {preferredTypes} = settings;

src/rules/noUndefinedTypes.js

@@ -108,7 +108,7 @@ export default iterateJsdoc(({
     .concat(closureGenericTypes);
 
   const jsdocTags = utils.filterTags((tag) => {
-    return utils.isTagWithType(tag.tag);
+    return utils.tagMightHaveType(tag.tag);
   });
 
   jsdocTags.forEach((tag) => {

src/rules/validTypes.js

@@ -62,14 +62,13 @@ export default iterateJsdoc(({
     };
 
     const hasType = Boolean(tag.type);
-    const mustHaveType = utils.isTagWithType(tag.tag) && !utils.isPotentiallyEmptyTypeTag(tag.tag);
+    const mustHaveType = utils.tagMustHaveType(tag.tag);
 
     const hasNamePath = Boolean(tag.name) && !(tag.tag === 'see' && !checkSeesForNamepaths);
-    const mustHaveNamepath = utils.isNamepathTag(tag.tag, checkSeesForNamepaths) &&
-      !utils.passesEmptyNamepathCheck(tag, allowEmptyNamepaths);
+    const mustHaveNamepath = utils.tagMustHaveNamepath(tag.tag) && !allowEmptyNamepaths;
 
     const hasEither = hasType || hasNamePath;
-    const mustHaveEither = utils.isTagWithMandatoryNamepathOrType(tag.tag);
+    const mustHaveEither = utils.tagMustHaveEitherTypeOrNamepath(tag.tag);
 
     if (tag.tag === 'borrows') {
       const thisNamepath = tag.description.replace(asExpression, '');