eslint-plugin-jsdoc - npm Package Compare versions

Comparing version 2.4.0 to 3.0.0

bin/readme-assertions.js

@@ -26,3 +26,3 @@ /**
 const getAssertions = () => {
-    const assertionFiles = glob.sync(path.resolve(__dirname, './../tests/rules/assertions/*.js'));
+    const assertionFiles = glob.sync(path.resolve(__dirname, '../test/rules/assertions/*.js'));
 
@@ -49,4 +49,7 @@ const assertionNames = _.map(assertionFiles, (filePath) => {
     let lines = _.trim(code).split('\n');
-    const indentSize = lines[lines.length - 1].match(/^\s+/)[0].length;
 
+    const indendation = lines[lines.length - 1].match(/^\s+/);
+
+    const indentSize = indendation ? indendation[0].length : 0;
+
     lines = _.map(lines, (line, i) => {
@@ -64,3 +67,3 @@ if (i === 0) {
 const updateDocuments = (assertions) => {
-    const readmeDocumentPath = path.join(__dirname, './../README.md');
+    const readmeDocumentPath = path.join(__dirname, '../README.md');
 
@@ -67,0 +70,0 @@ let documentBody = fs.readFileSync(readmeDocumentPath, 'utf8');

dist/iterateJsdoc.js

@@ -82,8 +82,8 @@ 'use strict';
       iterator({
-        context: context,
-        functionNode: functionNode,
-        jsdoc: jsdoc,
-        jsdocNode: jsdocNode,
-        report: report,
-        utils: utils
+        context,
+        functionNode,
+        jsdoc,
+        jsdocNode,
+        report,
+        utils
       });
@@ -90,0 +90,0 @@ };

dist/jsdocUtils.js

@@ -101,10 +101,10 @@ 'use strict';
 exports.default = {
-  getFunctionParameterNames: getFunctionParameterNames,
-  getJsdocParameterNames: getJsdocParameterNames,
-  getJsdocParameterNamesDeep: getJsdocParameterNamesDeep,
-  getPreferredTagName: getPreferredTagName,
-  hasTag: hasTag,
-  isValidTag: isValidTag
+  getFunctionParameterNames,
+  getJsdocParameterNames,
+  getJsdocParameterNamesDeep,
+  getPreferredTagName,
+  hasTag,
+  isValidTag
 };
 module.exports = exports['default'];
 //# sourceMappingURL=jsdocUtils.js.map

package.json

@@ -16,3 +16,3 @@ {
     "babel-plugin-transform-flow-strip-types": "^6.18.0",
-    "babel-preset-es2015": "^6.5.0",
+    "babel-preset-env": "^1.2.2",
     "babel-register": "^6.18.0",
@@ -24,4 +24,8 @@ "chai": "^3.5.0",
     "globby": "^4.0.0",
-    "mocha": "^2.5.3"
+    "mocha": "^2.5.3",
+    "semantic-release": "^6.3.2"
   },
+  "engines": {
+    "node": ">=5"
+  },
   "keywords": [
@@ -45,7 +49,7 @@ "eslint",
     "build": "NODE_ENV=production babel ./src --out-dir ./dist --copy-files --source-maps",
-    "generate-readme": "gitdown ./.README/README.md --output-file ./README.md && npm run readme-add-assertions",
+    "generate-readme": "gitdown ./.README/README.md --output-file ./README.md && npm run add-assertions",
     "lint": "eslint ./src ./test",
-    "test": "mocha --compilers js:babel-register && npm run lint"
+    "test": "mocha --compilers js:babel-register"
   },
-  "version": "2.4.0"
-}
+  "version": "3.0.0"
+}

README.md

@@ -1,2 +0,3 @@
-<h1 id="eslint-plugin-jsdoc">eslint-plugin-jsdoc</h1>
+<a name="eslint-plugin-jsdoc"></a>
+# eslint-plugin-jsdoc
 
@@ -15,2 +16,3 @@ [![NPM version](http://img.shields.io/npm/v/eslint-plugin-jsdoc.svg?style=flat-square)](https://www.npmjs.org/package/eslint-plugin-jsdoc)
         * [Alias Preference](#eslint-plugin-jsdoc-settings-alias-preference)
+        * [Additional Tag Names](#eslint-plugin-jsdoc-settings-additional-tag-names)
     * [Rules](#eslint-plugin-jsdoc-rules)
@@ -30,3 +32,4 @@ * [`check-param-names`](#eslint-plugin-jsdoc-rules-check-param-names)
 
-<h3 id="eslint-plugin-jsdoc-reference-to-jscs-jsdoc">Reference to jscs-jsdoc</h3>
+<a name="eslint-plugin-jsdoc-reference-to-jscs-jsdoc"></a>
+### Reference to jscs-jsdoc
 
@@ -55,3 +58,4 @@ This table maps the rules between `eslint-plugin-jsdoc` and `jscs-jsdoc`.
 
-<h2 id="eslint-plugin-jsdoc-installation">Installation</h2>
+<a name="eslint-plugin-jsdoc-installation"></a>
+## Installation
 
@@ -70,3 +74,4 @@ Install [ESLint](https://www.github.com/eslint/eslint) either locally or globally.
 
-<h2 id="eslint-plugin-jsdoc-configuration">Configuration</h2>
+<a name="eslint-plugin-jsdoc-configuration"></a>
+## Configuration
 
@@ -103,5 +108,7 @@ Add `plugins` section and specify `eslint-plugin-jsdoc` as a plugin.
 
-<h2 id="eslint-plugin-jsdoc-settings">Settings</h2>
+<a name="eslint-plugin-jsdoc-settings"></a>
+## Settings
 
-<h3 id="eslint-plugin-jsdoc-settings-alias-preference">Alias Preference</h3>
+<a name="eslint-plugin-jsdoc-settings-alias-preference"></a>
+### Alias Preference
 
@@ -124,6 +131,27 @@ Use `settings.jsdoc.tagNamePreference` to configure a preferred alias name for a JSDoc tag. The format of the configuration is: `<primary tag name>: <preferred alias name>`, e.g.
 
-<h2 id="eslint-plugin-jsdoc-rules">Rules</h2>
 
-<h3 id="eslint-plugin-jsdoc-rules-check-param-names"><code>check-param-names</code></h3>
+<a name="eslint-plugin-jsdoc-settings-additional-tag-names"></a>
+### Additional Tag Names
 
+Use `settings.jsdoc.additionalTagNames` to configure additional, allowed JSDoc tags. The format of the configuration is as follows:
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "additionalTagNames": {
+                "customTags": ["define", "extends", "record"]
+            }
+        }
+    }
+}
+```
+
+<a name="eslint-plugin-jsdoc-rules"></a>
+## Rules
+
+<a name="eslint-plugin-jsdoc-rules-check-param-names"></a>
+### <code>check-param-names</code>
+
 Ensures that parameter names in JSDoc match those in the function declaration.
@@ -258,3 +286,4 @@
 
-<h4 id="eslint-plugin-jsdoc-rules-check-param-names-deconstructing-function-parameter">Deconstructing Function Parameter</h4>
+<a name="eslint-plugin-jsdoc-rules-check-param-names-deconstructing-function-parameter"></a>
+#### Deconstructing Function Parameter
 
@@ -277,3 +306,4 @@ `eslint-plugin-jsdoc` does not validate names of parameters in function deconstruction, e.g.
 
-<h3 id="eslint-plugin-jsdoc-rules-check-tag-names"><code>check-tag-names</code></h3>
+<a name="eslint-plugin-jsdoc-rules-check-tag-names"></a>
+### <code>check-tag-names</code>
 
@@ -388,2 +418,27 @@ Reports invalid block tag names.
 // Message: Invalid JSDoc tag (preference). Replace "param" JSDoc tag with "arg".
+
+/**
+ * @bar foo
+ */
+function quux (foo) {
+
+}
+// Message: Invalid JSDoc tag name "bar".
+
+/**
+ * @baz @bar foo
+ */
+function quux (foo) {
+
+}
+// Message: Invalid JSDoc tag name "baz".
+
+/**
+ * @bar
+ * @baz
+ */
+function quux (foo) {
+
+}
+// Message: Invalid JSDoc tag name "baz".
 ```
@@ -407,6 +462,87 @@
 }
+
+/**
+ * @bar foo
+ */
+function quux (foo) {
+
+}
+
+/**
+ * @baz @bar foo
+ */
+function quux (foo) {
+
+}
+
+/** 
+ * @abstract
+ * @access
+ * @alias
+ * @augments
+ * @author
+ * @borrows
+ * @callback
+ * @class
+ * @classdesc
+ * @constant
+ * @constructs
+ * @copyright
+ * @default
+ * @deprecated
+ * @description
+ * @enum
+ * @event
+ * @example
+ * @exports
+ * @external
+ * @file
+ * @fires
+ * @function
+ * @global
+ * @ignore
+ * @implements
+ * @inheritdoc
+ * @inner
+ * @instance
+ * @interface
+ * @kind
+ * @lends
+ * @license
+ * @listens
+ * @member
+ * @memberof
+ * @mixes
+ * @mixin
+ * @module
+ * @name
+ * @namespace
+ * @override
+ * @param
+ * @private
+ * @property
+ * @protected
+ * @public
+ * @readonly
+ * @requires
+ * @returns
+ * @see
+ * @since
+ * @static
+ * @summary
+ * @this
+ * @throws
+ * @todo
+ * @tutorial
+ * @type
+ * @typedef
+ * @variation
+ * @version
+ */
+function quux (foo) {}
 ```
 
 
-<h3 id="eslint-plugin-jsdoc-rules-check-types"><code>check-types</code></h3>
+<a name="eslint-plugin-jsdoc-rules-check-types"></a>
+### <code>check-types</code>
 
@@ -427,2 +563,33 @@ Reports invalid types.
 
+<a name="eslint-plugin-jsdoc-rules-check-types-why-not-capital-case-everything"></a>
+#### Why not capital case everything?
+
+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. 
+
+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.
+
+```js
+new String('lard') // String {0: "l", 1: "a", 2: "r", 3: "d", length: 4}
+'lard' // "lard"
+new String('lard') === 'lard' // false
+```
+
+To make things more confusing, there are also object literals and object Objects. But object literals are still static Objects and object Objects are instantiated Objects. So an object primitive is still an object Object.
+
+Basically, for primitives, we want to define the type as a primitive, because that's what we use in 99.9% of cases. For everything else, we use the type rather than the primitive. Otherwise it would all just be `{object}`.
+
+In short: It's not about consistency, rather about the 99.9% use case.
+
+type name | `typeof` | check-types | testcase
+--|--|--|--
+**Object** | object | **Object** | `({}) instanceof Object` -> `true`
+**Array** | object | **Array** | `([]) instanceof Array` -> `true`
+**Date** | object | **Date** | `(new Date()) instanceof Date` -> `true`
+**RegExp** | object | **RegExp** | `(new RegExp(/.+/)) instanceof RegExp` -> `true`
+Boolean | **boolean** | **boolean** | `(true) instanceof Boolean` -> **`false`**
+Number | **number** | **number** | `(41) instanceof Number` -> **`false`**
+String | **string** | **string** | `("test") instanceof String` -> **`false`**
+
 |||
@@ -476,3 +643,4 @@ |---|---|
 
-<h3 id="eslint-plugin-jsdoc-rules-newline-after-description"><code>newline-after-description</code></h3>
+<a name="eslint-plugin-jsdoc-rules-newline-after-description"></a>
+### <code>newline-after-description</code>
 
@@ -557,3 +725,4 @@ Enforces a consistent padding of the block description.
 
-<h3 id="eslint-plugin-jsdoc-rules-require-description-complete-sentence"><code>require-description-complete-sentence</code></h3>
+<a name="eslint-plugin-jsdoc-rules-require-description-complete-sentence"></a>
+### <code>require-description-complete-sentence</code>
 
@@ -682,3 +851,4 @@ Requires that block description and tag description are written in complete sentences, i.e.,
 
-<h3 id="eslint-plugin-jsdoc-rules-require-hyphen-before-param-description"><code>require-hyphen-before-param-description</code></h3>
+<a name="eslint-plugin-jsdoc-rules-require-hyphen-before-param-description"></a>
+### <code>require-hyphen-before-param-description</code>
 
@@ -716,3 +886,4 @@ Requires a hyphen before the `@param` description.
 
-<h3 id="eslint-plugin-jsdoc-rules-require-param"><code>require-param</code></h3>
+<a name="eslint-plugin-jsdoc-rules-require-param"></a>
+### <code>require-param</code>
 
@@ -765,2 +936,9 @@ Requires that all function parameters are documented.
 /**
+ * @inheritdoc
+ */
+function quux (foo) {
+
+}
+
+/**
  * @arg foo
@@ -774,3 +952,4 @@ */
 
-<h3 id="eslint-plugin-jsdoc-rules-require-param-description"><code>require-param-description</code></h3>
+<a name="eslint-plugin-jsdoc-rules-require-param-description"></a>
+### <code>require-param-description</code>
 
@@ -823,3 +1002,4 @@ Requires that `@param` tag has `description` value.
 
-<h3 id="eslint-plugin-jsdoc-rules-require-param-type"><code>require-param-type</code></h3>
+<a name="eslint-plugin-jsdoc-rules-require-param-type"></a>
+### <code>require-param-type</code>
 
@@ -872,3 +1052,4 @@ Requires that `@param` tag has `type` value.
 
-<h3 id="eslint-plugin-jsdoc-rules-require-returns-description"><code>require-returns-description</code></h3>
+<a name="eslint-plugin-jsdoc-rules-require-returns-description"></a>
+### <code>require-returns-description</code>
 
@@ -921,3 +1102,4 @@ Requires that `@returns` tag has `description` value.
 
-<h3 id="eslint-plugin-jsdoc-rules-require-returns-type"><code>require-returns-type</code></h3>
+<a name="eslint-plugin-jsdoc-rules-require-returns-type"></a>
+### <code>require-returns-type</code>
 
@@ -924,0 +1106,0 @@ Requires that `@returns` tag has `type` value.

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

90989

increased by4.56%

Lines of code

698

increased by0.14%

Number of lines in readme file

1133

increased by19.14%

Worsened metrics

Dev dependency count

12

increased by9.09%

No dependency changes