eslint-plugin-jsdoc 39.6.7 → 39.6.8

package/README.md

@@ -17813,7 +17813,7 @@ function quux () {
 // Message: JSDoc @returns declaration present but return expression not available in function.
 
 /**
- * @returns Baz.
+ * @returns {SomeType} Baz.
  */
 function foo() {
     switch (true) {
@@ -17827,7 +17827,7 @@ function foo() {
 // Message: JSDoc @returns declaration present but return expression not available in function.
 
 /**
- * @returns Baz.
+ * @returns {SomeType} Baz.
  */
 function foo() {
     switch (true) {
@@ -18243,6 +18243,16 @@ function assertNumber(val) {
  */
 export function readFixture(path: string): Promise<Buffer>;
 
+/**
+ * Reads a test fixture.
+ *
+ * @param path The path to resolve relative to the fixture base. It will be normalized for the
+ * operating system.
+ *
+ * @returns {SomeType} The file contents as buffer.
+ */
+export function readFixture(path: string): Promise<Buffer>;
+
 /**
  * Reads a test fixture.
  *
@@ -18430,6 +18440,41 @@ function foo( bar ) {
     return functionWithUnknownReturnType();
   }
 }
+
+/**
+ * @returns Baz.
+ */
+function foo() {
+    switch (true) {
+        default:
+            switch (false) {
+                default: return;
+            }
+            return "baz";
+    }
+};
+
+/**
+ * @returns Baz.
+ */
+function foo() {
+    switch (true) {
+        default:
+            switch (false) {
+                default: return;
+            }
+            return "baz";
+    }
+};
+
+/**
+ * @returns
+ */
+const quux = (someVar) => {
+  if (someVar) {
+    return true;
+  }
+};
 ````
 
 

package/dist/rules/requireReturnsCheck.js

@@ -69,7 +69,7 @@ var _default = (0, _iterateJsdoc.default)(({
   }
 
   // In case a return value is declared in JSDoc, we also expect one in the code.
-  if (!returnNever && (reportMissingReturnForUndefinedTypes || !utils.mayBeUndefinedTypeTag(tag)) && !utils.hasValueOrExecutorHasNonEmptyResolveValue(exemptAsync, true) && (!exemptGenerators || !node.generator)) {
+  if (!returnNever && (reportMissingReturnForUndefinedTypes || !utils.mayBeUndefinedTypeTag(tag)) && (tag.type === '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(exemptAsync) || tag.type !== '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(exemptAsync, true)) && (!exemptGenerators || !node.generator)) {
     report(`JSDoc @${tagName} declaration present but return expression not available in function.`);
   }
 }, {

package/dist/rules/requireReturnsCheck.js.map

@@ -1 +1 @@
-{"version":3,"file":"requireReturnsCheck.js","names":["canSkip","utils","settings","voidingTags","mode","push","hasATag","isConstructor","classHasTag","iterateJsdoc","context","node","report","exemptAsync","exemptGenerators","reportMissingReturnForUndefinedTypes","options","isAsync","tagName","getPreferredTagName","tags","getTags","length","tag","type","trim","test","returnNever","hasValueOrExecutorHasNonEmptyResolveValue","mayBeUndefinedTypeTag","generator","meta","docs","description","url","schema","additionalProperties","properties","default"],"sources":["../../src/rules/requireReturnsCheck.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc';\n\nconst canSkip = (utils, settings) => {\n  const voidingTags = [\n    // An abstract function is by definition incomplete\n    // so it is perfectly fine if a return is documented but\n    // not present within the function.\n    // A subclass may inherit the doc and implement the\n    // missing return.\n    'abstract',\n    'virtual',\n\n    // A constructor function returns `this` by default, so may be `@returns`\n    //   tag indicating this but no explicit return\n    'class',\n    'constructor',\n    'interface',\n  ];\n\n  if (settings.mode === 'closure') {\n    // Structural Interface in GCC terms, equivalent to @interface tag as far as this rule is concerned\n    voidingTags.push('record');\n  }\n\n  return utils.hasATag(voidingTags) ||\n    utils.isConstructor() ||\n    utils.classHasTag('interface') ||\n    settings.mode === 'closure' && utils.classHasTag('record');\n};\n\nexport default iterateJsdoc(({\n  context,\n  node,\n  report,\n  settings,\n  utils,\n}) => {\n  const {\n    exemptAsync = true,\n    exemptGenerators = settings.mode === 'typescript',\n    reportMissingReturnForUndefinedTypes = false,\n  } = context.options[0] || {};\n\n  if (canSkip(utils, settings)) {\n    return;\n  }\n\n  if (exemptAsync && utils.isAsync()) {\n    return;\n  }\n\n  const tagName = utils.getPreferredTagName({\n    tagName: 'returns',\n  });\n  if (!tagName) {\n    return;\n  }\n\n  const tags = utils.getTags(tagName);\n\n  if (tags.length === 0) {\n    return;\n  }\n\n  if (tags.length > 1) {\n    report(`Found more than one @${tagName} declaration.`);\n\n    return;\n  }\n\n  const [\n    tag,\n  ] = tags;\n\n  const type = tag.type.trim();\n\n  // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n  if (/asserts\\s/u.test(type)) {\n    return;\n  }\n\n  const returnNever = type === 'never';\n\n  if (returnNever && utils.hasValueOrExecutorHasNonEmptyResolveValue(false)) {\n    report(`JSDoc @${tagName} declaration set with \"never\" but return expression is present in function.`);\n\n    return;\n  }\n\n  // In case a return value is declared in JSDoc, we also expect one in the code.\n  if (\n    !returnNever &&\n    (\n      reportMissingReturnForUndefinedTypes ||\n      !utils.mayBeUndefinedTypeTag(tag)\n    ) &&\n    !utils.hasValueOrExecutorHasNonEmptyResolveValue(\n      exemptAsync,\n      true,\n    ) && (!exemptGenerators || !node.generator)\n  ) {\n    report(`JSDoc @${tagName} declaration present but return expression not available in function.`);\n  }\n}, {\n  meta: {\n    docs: {\n      description: 'Requires a return statement in function body if a `@returns` tag is specified in jsdoc comment.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns-check',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          exemptAsync: {\n            default: true,\n            type: 'boolean',\n          },\n          exemptGenerators: {\n            type: 'boolean',\n          },\n          reportMissingReturnForUndefinedTypes: {\n            default: false,\n            type: 'boolean',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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"}
+{"version":3,"file":"requireReturnsCheck.js","names":["canSkip","utils","settings","voidingTags","mode","push","hasATag","isConstructor","classHasTag","iterateJsdoc","context","node","report","exemptAsync","exemptGenerators","reportMissingReturnForUndefinedTypes","options","isAsync","tagName","getPreferredTagName","tags","getTags","length","tag","type","trim","test","returnNever","hasValueOrExecutorHasNonEmptyResolveValue","mayBeUndefinedTypeTag","generator","meta","docs","description","url","schema","additionalProperties","properties","default"],"sources":["../../src/rules/requireReturnsCheck.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc';\n\nconst canSkip = (utils, settings) => {\n  const voidingTags = [\n    // An abstract function is by definition incomplete\n    // so it is perfectly fine if a return is documented but\n    // not present within the function.\n    // A subclass may inherit the doc and implement the\n    // missing return.\n    'abstract',\n    'virtual',\n\n    // A constructor function returns `this` by default, so may be `@returns`\n    //   tag indicating this but no explicit return\n    'class',\n    'constructor',\n    'interface',\n  ];\n\n  if (settings.mode === 'closure') {\n    // Structural Interface in GCC terms, equivalent to @interface tag as far as this rule is concerned\n    voidingTags.push('record');\n  }\n\n  return utils.hasATag(voidingTags) ||\n    utils.isConstructor() ||\n    utils.classHasTag('interface') ||\n    settings.mode === 'closure' && utils.classHasTag('record');\n};\n\nexport default iterateJsdoc(({\n  context,\n  node,\n  report,\n  settings,\n  utils,\n}) => {\n  const {\n    exemptAsync = true,\n    exemptGenerators = settings.mode === 'typescript',\n    reportMissingReturnForUndefinedTypes = false,\n  } = context.options[0] || {};\n\n  if (canSkip(utils, settings)) {\n    return;\n  }\n\n  if (exemptAsync && utils.isAsync()) {\n    return;\n  }\n\n  const tagName = utils.getPreferredTagName({\n    tagName: 'returns',\n  });\n  if (!tagName) {\n    return;\n  }\n\n  const tags = utils.getTags(tagName);\n\n  if (tags.length === 0) {\n    return;\n  }\n\n  if (tags.length > 1) {\n    report(`Found more than one @${tagName} declaration.`);\n\n    return;\n  }\n\n  const [\n    tag,\n  ] = tags;\n\n  const type = tag.type.trim();\n\n  // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n  if (/asserts\\s/u.test(type)) {\n    return;\n  }\n\n  const returnNever = type === 'never';\n\n  if (returnNever && utils.hasValueOrExecutorHasNonEmptyResolveValue(false)) {\n    report(`JSDoc @${tagName} declaration set with \"never\" but return expression is present in function.`);\n\n    return;\n  }\n\n  // In case a return value is declared in JSDoc, we also expect one in the code.\n  if (\n    !returnNever &&\n    (\n      reportMissingReturnForUndefinedTypes ||\n      !utils.mayBeUndefinedTypeTag(tag)\n    ) &&\n    (tag.type === '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(\n      exemptAsync,\n    ) ||\n    tag.type !== '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(\n      exemptAsync,\n      true,\n    )) &&\n    (!exemptGenerators || !node.generator)\n  ) {\n    report(`JSDoc @${tagName} declaration present but return expression not available in function.`);\n  }\n}, {\n  meta: {\n    docs: {\n      description: 'Requires a return statement in function body if a `@returns` tag is specified in jsdoc comment.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns-check',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          exemptAsync: {\n            default: true,\n            type: 'boolean',\n          },\n          exemptGenerators: {\n            type: 'boolean',\n          },\n          reportMissingReturnForUndefinedTypes: {\n            default: false,\n            type: 'boolean',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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"}

package/package.json

@@ -120,5 +120,5 @@
     "test-cov": "cross-env TIMING=1 nyc --reporter text npm run test-no-cov",
     "test-index": "npm run test-no-cov -- test/rules/index.js"
   },
-  "version": "39.6.7"
+  "version": "39.6.8"
 }