eslint-plugin-jsdoc - npm Package Compare versions

Comparing version 4.8.3 to 4.8.4

dist/index.js

@@ -52,2 +52,4 @@ "use strict";
 
+var _requireJsdoc = _interopRequireDefault(require("./rules/requireJsdoc"));
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
@@ -73,2 +75,3 @@
         'jsdoc/require-hyphen-before-param-description': 'off',
+        'jsdoc/require-jsdoc': 'warn',
         'jsdoc/require-param': 'warn',
@@ -100,2 +103,3 @@ 'jsdoc/require-param-description': 'warn',
     'require-hyphen-before-param-description': _requireHyphenBeforeParamDescription.default,
+    'require-jsdoc': _requireJsdoc.default,
     'require-param': _requireParam.default,
@@ -102,0 +106,0 @@ 'require-param-description': _requireParamDescription.default,

dist/iterateJsdoc.js

@@ -32,3 +32,3 @@ "use strict";
 
-var curryUtils = function curryUtils(functionNode, jsdoc, tagNamePreference, exampleCodeRegex, rejectExampleCodeRegex, additionalTagNames, baseConfig, configFile, captionRequired, matchingFileName, eslintrcForExamples, allowInlineConfig, reportUnusedDisableDirectives, noDefaultExampleRules, allowOverrideWithoutParam, allowImplementsWithoutParam, allowAugmentsExtendsWithoutParam, ancestors, sourceCode) {
+var curryUtils = function curryUtils(functionNode, jsdoc, tagNamePreference, exampleCodeRegex, rejectExampleCodeRegex, additionalTagNames, baseConfig, configFile, captionRequired, matchingFileName, eslintrcForExamples, allowInlineConfig, allowEmptyNamepaths, reportUnusedDisableDirectives, noDefaultExampleRules, allowOverrideWithoutParam, allowImplementsWithoutParam, allowAugmentsExtendsWithoutParam, checkSeesForNamepaths, ancestors, sourceCode) {
   var utils = {};
@@ -124,2 +124,11 @@
 
+  utils.isNamepathType = function (tagName) {
+    return _jsdocUtils.default.isNamepathType(tagName, checkSeesForNamepaths);
+  };
+
+  utils.passesEmptyNamepathCheck = function (tag) {
+    return !tag.name && allowEmptyNamepaths && _lodash.default.includes([// These may serve some minor purpose when empty
+    'callback', 'event', 'listens', 'fires', 'emits'], tag.tag);
+  };
+
   utils.getClassJsdocNode = function () {
@@ -170,2 +179,3 @@ var greatGrandParent = ancestors.slice(-3)[0];
     var allowInlineConfig = _lodash.default.get(context, 'settings.jsdoc.allowInlineConfig') !== false;
+    var allowEmptyNamepaths = _lodash.default.get(context, 'settings.jsdoc.allowEmptyNamepaths') !== false;
     var reportUnusedDisableDirectives = _lodash.default.get(context, 'settings.jsdoc.reportUnusedDisableDirectives') !== false;
@@ -177,2 +187,3 @@ var captionRequired = Boolean(_lodash.default.get(context, 'settings.jsdoc.captionRequired'));
     var allowAugmentsExtendsWithoutParam = Boolean(_lodash.default.get(context, 'settings.jsdoc.allowAugmentsExtendsWithoutParam'));
+    var checkSeesForNamepaths = Boolean(_lodash.default.get(context, 'settings.jsdoc.checkSeesForNamepaths'));
 
@@ -231,3 +242,3 @@ var checkJsdoc = function checkJsdoc(functionNode) {
 
-      var utils = curryUtils(functionNode, jsdoc, tagNamePreference, exampleCodeRegex, rejectExampleCodeRegex, additionalTagNames, baseConfig, configFile, captionRequired, matchingFileName, eslintrcForExamples, allowInlineConfig, reportUnusedDisableDirectives, noDefaultExampleRules, allowOverrideWithoutParam, allowImplementsWithoutParam, allowAugmentsExtendsWithoutParam, ancestors, sourceCode);
+      var utils = curryUtils(functionNode, jsdoc, tagNamePreference, exampleCodeRegex, rejectExampleCodeRegex, additionalTagNames, baseConfig, configFile, captionRequired, matchingFileName, eslintrcForExamples, allowInlineConfig, allowEmptyNamepaths, reportUnusedDisableDirectives, noDefaultExampleRules, allowOverrideWithoutParam, allowImplementsWithoutParam, allowAugmentsExtendsWithoutParam, checkSeesForNamepaths, ancestors, sourceCode);
       iterator({
@@ -234,0 +245,0 @@ context,

dist/jsdocUtils.js

@@ -101,2 +101,8 @@ "use strict";
 
+var namepathAsNameTags = ['alias', 'augments', 'callback', 'extends', 'lends', 'memberof', 'memberof!', 'mixes', 'name', 'this', 'emits', 'event', 'fires', 'listens'];
+
+var isNamepathType = function isNamepathType(tagName, checkSeesForNamepaths) {
+  return _lodash.default.includes(namepathAsNameTags, tagName) || tagName === 'see' && checkSeesForNamepaths;
+};
+
 var _default = {
@@ -109,2 +115,3 @@ getFunctionParameterNames,
   hasTag,
+  isNamepathType,
   isValidTag
@@ -111,0 +118,0 @@ };

dist/rules/checkSyntax.js

@@ -16,3 +16,3 @@ "use strict";
 
-  if (!jsdoc.tags.length) {
+  if (!jsdoc.tags) {
     return;
@@ -19,0 +19,0 @@ }

dist/rules/checkTagNames.js

@@ -27,3 +27,3 @@ "use strict";
         report('Invalid JSDoc tag (preference). Replace "' + jsdocTag.tag + '" JSDoc tag with "' + preferredTagName + '".', function (fixer) {
-          var replacement = sourceCode.getText(jsdocNode).replace(jsdocTag.tag, preferredTagName);
+          var replacement = sourceCode.getText(jsdocNode).replace('@' + jsdocTag.tag, '@' + preferredTagName);
           return fixer.replaceText(jsdocNode, replacement);
@@ -30,0 +30,0 @@ });

dist/rules/checkTypes.js

@@ -19,3 +19,3 @@ "use strict";
 targetTags = targetTags.concat(targetTagAliases);
-var strictNativeTypes = ['boolean', 'number', 'string', 'Array', 'Object', 'RegExp', 'Date', 'Function'];
+var strictNativeTypes = ['undefined', 'null', 'boolean', 'number', 'string', 'Array', 'Object', 'RegExp', 'Date', 'Function'];
 
@@ -22,0 +22,0 @@ var _default = (0, _iterateJsdoc.default)(function (_ref) {

dist/rules/noUndefinedTypes.js

@@ -18,3 +18,4 @@ "use strict";
 
-var extraTypes = ['string', 'number', 'boolean', 'any', '*'];
+var extraTypes = ['null', 'undefined', 'string', 'number', 'boolean', 'any', '*', 'Array', 'Object', 'RegExp', 'Date', 'Function'];
+var tagsWithNames = ['callback', 'class', 'constructor', 'constant', 'const', 'event', 'external', 'host', 'function', 'func', 'method', 'interface', 'member', 'var', 'mixin', 'name', 'namespace', 'type', 'typedef'];
 
@@ -32,3 +33,3 @@ var _default = (0, _iterateJsdoc.default)(function (_ref) {
     return (doc.tags || []).filter(function (tag) {
-      return tag.tag === 'typedef';
+      return _lodash.default.includes(tagsWithNames, tag.tag);
     });
@@ -35,0 +36,0 @@ }).map(function (tag) {

dist/rules/validTypes.js

@@ -21,15 +21,43 @@ "use strict";
 
+var asExpression = /as\s+/;
+
 var _default = (0, _iterateJsdoc.default)(function (_ref) {
   var jsdoc = _ref.jsdoc,
-      report = _ref.report;
+      report = _ref.report,
+      utils = _ref.utils;
 
   _lodash.default.forEach(jsdoc.tags, function (tag) {
-    if (tag.type && !isLink(tag.type)) {
+    var validTypeParsing = function validTypeParsing(type) {
       try {
-        (0, _jsdoctypeparser.parse)(tag.type);
+        (0, _jsdoctypeparser.parse)(type);
       } catch (error) {
         if (error.name === 'SyntaxError') {
-          report('Syntax error in type: ' + tag.type, null, tag);
+          report('Syntax error in type: ' + type, null, tag);
+          return false;
         }
       }
+
+      return true;
+    };
+
+    if (tag.tag === 'borrows') {
+      var thisNamepath = tag.description.replace(asExpression, '');
+
+      if (!asExpression.test(tag.description) || !thisNamepath) {
+        report('@borrows must have an "as" expression. Found "' + tag.description + '"', null, tag);
+        return;
+      }
+
+      if (validTypeParsing(thisNamepath)) {
+        var thatNamepath = tag.name;
+        validTypeParsing(thatNamepath);
+      }
+    } else if (utils.isNamepathType(tag.tag)) {
+      if (utils.passesEmptyNamepathCheck(tag)) {
+        return;
+      }
+
+      validTypeParsing(tag.name);
+    } else if (tag.type && !isLink(tag.type)) {
+      validTypeParsing(tag.type);
     }
@@ -36,0 +64,0 @@ });

dist/tagNames.js

@@ -47,2 +47,3 @@ "use strict";
   memberof: [],
+  'memberof!': [],
   mixes: [],
@@ -49,0 +50,0 @@ mixin: [],

package.json

@@ -63,3 +63,3 @@ {
   },
-  "version": "4.8.3"
+  "version": "4.8.4"
 }

README.md

 <a name="eslint-plugin-jsdoc"></a>
 # eslint-plugin-jsdoc
 
+[![GitSpo Mentions](https://gitspo.com/badges/mentions/gajus/eslint-plugin-jsdoc?style=flat-square)](https://gitspo.com/mentions/gajus/eslint-plugin-jsdoc)
 [![NPM version](http://img.shields.io/npm/v/eslint-plugin-jsdoc.svg?style=flat-square)](https://www.npmjs.org/package/eslint-plugin-jsdoc)
@@ -827,2 +828,9 @@ [![Travis build status](http://img.shields.io/travis/gajus/eslint-plugin-jsdoc/master.svg?style=flat-square)](https://travis-ci.org/gajus/eslint-plugin-jsdoc)
 }
+
+/**
+ *
+ */
+function quux (foo) {
+
+}
 ````
@@ -878,2 +886,3 @@
 memberof
+memberof!
 mixes
@@ -998,2 +1007,9 @@ mixin
 /**
+ * @memberof! foo
+ */
+function quux (foo) {
+
+}
+
+/**
  * @arg foo
@@ -1059,2 +1075,3 @@ */
  * @memberof
+ * @memberof!
  * @mixes
@@ -1099,2 +1116,4 @@ * @mixin
 ```
+undefined
+null
 boolean
@@ -1112,5 +1131,5 @@ number
 
-Why are `boolean`, `number` and `string` exempt from starting with a capital letter? Let's take `string` as an example. In Javascript, everything is an object. The string Object has prototypes for string functions such as `.toUpperCase()`. 
+Why are `boolean`, `number` and `string` exempt from starting with a capital letter? Let's take `string` as an example. In Javascript, everything is an object. The string Object has prototypes for string functions such as `.toUpperCase()`.
 
-Fortunately we don't have to write `new String()` everywhere in our code. Javascript will automatically wrap string primitives into string Objects when we're applying a string function to a string primitive. This way the memory footprint is a tiny little bit smaller, and the [GC](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)) has less work to do. 
+Fortunately we don't have to write `new String()` everywhere in our code. Javascript will automatically wrap string primitives into string Objects when we're applying a string function to a string primitive. This way the memory footprint is a tiny little bit smaller, and the [GC](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)) has less work to do.
 
@@ -1420,2 +1439,17 @@ So in a sense, there two types of strings in Javascript; `{string}` literals, also called primitives and `{String}` Objects. We use the primitives because it's easier to write and uses less memory. `{String}` and `{string}` are technically both valid, but they are not the same.
 }
+
+/**
+ * Callback test.
+ *
+ * @callback addStuffCallback
+ * @param {String} sum - An test integer.
+ */
+/**
+ * Test Eslint.
+ *
+ * @param {addStuffCallback} callback - A callback to run.
+ */
+function testFunction(callback) {
+  callback();
+}
 ````
@@ -2689,2 +2723,14 @@
 
+Also impacts behaviors on namepath-pointing or event-pointing tags:
+
+1.  `@alias`, `@augments`, `@extends`, `@lends`, `@memberof`, `@memberof!`, `@mixes`, `@name`, `@this`
+1.  `@callback`, `@event`, `@listens`, `@fires`, `@emits`
+1.  `@borrows`
+
+The following apply to the above sets:
+
+-   Expect tags in set 1 or 2 to have a valid namepath if present
+-   Prevent set 2 from being empty by setting `allowEmptyNamepaths` to `false` as these tags might have some indicative value without a path (but set 1 will always fail if empty)
+-   For the special case of set 3, i.e., `@borrows <that namepath> as <this namepath>`, check that both namepaths are present and valid and ensure there is an `as ` between them.
+
 |||
@@ -2705,2 +2751,52 @@ |---|---|
 // Message: Syntax error in type: Array<string
+
+/**
+ * @borrows foo% as bar
+ */
+function quux() {
+
+}
+// Message: Syntax error in type: foo%
+
+/**
+ * @borrows foo as bar%
+ */
+function quux() {
+
+}
+// Message: Syntax error in type: bar%
+
+/**
+ * @borrows foo
+ */
+function quux() {
+
+}
+// Message: @borrows must have an "as" expression. Found ""
+
+/**
+ * @see foo%
+ */
+function quux() {
+
+}
+// Settings: {"jsdoc":{"checkSeesForNamepaths":true}}
+// Message: Syntax error in type: foo%
+
+/**
+ * @alias module:abc#event:foo-bar
+ */
+function quux() {
+
+}
+// Message: Syntax error in type: module:abc#event:foo-bar
+
+/**
+ * @callback
+ */
+function quux() {
+
+}
+// Settings: {"jsdoc":{"allowEmptyNamepaths":false}}
+// Message: Syntax error in type: 
 ````
@@ -2733,2 +2829,30 @@
 /**
+ * @borrows foo as bar
+ */
+function quux() {
+
+}
+
+/**
+ * @see foo%
+ */
+function quux() {
+
+}
+
+/**
+ * @alias module:svgcanvas.SvgCanvas#event:ext_langReady
+ */
+function quux() {
+
+}
+
+/**
+ * @callback
+ */
+function quux() {
+
+}
+
+/**
  * @see {@link foo}
@@ -2735,0 +2859,0 @@ */

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

250360

increased by9.12%

Number of package files

59

increased by3.51%

Lines of code

1715

increased by11.51%

Number of lines in readme file

2856

increased by4.54%

No dependency changes