jscs-jsdoc - npm Package Compare versions

Comparing version 0.0.21 to 0.0.22

lib/jsdoc.js

@@ -125,4 +125,9 @@ var assert = require('assert');
     this.optional = parsed.optional;
+    this.variable = parsed.variable;
     this.valid = parsed.valid;
 
+    if (parsed.valid && parsed.variable) {
+        this.loc.column = this.loc.column + 3;
+    }
+
     /**
@@ -129,0 +134,0 @@ * match type

lib/rules/validate-jsdoc/check-param-names.js

@@ -17,2 +17,15 @@ module.exports = validateCheckParamNames;
 
+    // outOfOrder
+    var paramsByName = {};
+    node.params.forEach(function(param) {
+        paramsByName[param.name] = param;
+    });
+    var paramTagsByName = {};
+    node.jsdoc.iterateByType(['param', 'arg', 'argument'], function(tag) {
+        if (tag.name && tag.name.value) {
+            paramTagsByName[tag.name.value] = tag;
+        }
+    });
+    var outOfOrder = {};
+
     node.jsdoc.iterateByType(['param', 'arg', 'argument'],
@@ -37,7 +50,17 @@ /**
             // checking name
-            if (tag.name.value !== param.name) {
-                return err('expected ' + param.name + ' but got ' + tag.name.value,
-                    tag.name.loc || node.jsdoc.loc.start);
+            var msg;
+            if (tag.name.value !== param.name && !outOfOrder[tag.name.value]) {
+                if (paramsByName[tag.name.value] && paramTagsByName[param.name]) {
+                    outOfOrder[tag.name.value] = outOfOrder[param.name] = true;
+                    msg = 'parameters ' + tag.name.value + ' and ' + param.name + ' are out of order';
+                } else if (paramsByName[tag.name.value]) {
+                    outOfOrder[tag.name.value] = true;
+                    msg = 'parameter ' + tag.name.value + ' is out of order';
+                } else {
+                    msg = 'expected ' + param.name + ' but got ' + tag.name.value;
+                }
+
+                return err(msg, tag.name.loc || node.jsdoc.loc.start);
             }
         });
 }

lib/rules/validate-jsdoc/check-types.js

@@ -60,3 +60,3 @@ var jsdoc = require('../../jsdoc');
                 // throw an error if not valid
-                errors.add('jsDoc checkTypes: Expected valid type instead of ' + tag.type.value, tag.type.loc);
+                errors.add('expects valid type instead of ' + tag.type.value, tag.type.loc);
             }
@@ -63,0 +63,0 @@ });

lib/rules/validate-jsdoc/index.js

@@ -22,8 +22,8 @@ var assert = require('assert');
     value: function loadValidators(passedOptions) {
-        var validators = [];
-
         if (!passedOptions) {
-            return validators;
+            return [];
         }
 
+        var validators = [];
+
         Object.keys(validatorsByName).forEach(function(name) {
@@ -54,3 +54,4 @@ var v = validatorsByName[name];
     value: function checkOptions(validator, options) {
-        Object.keys(validator.options).forEach(function(data, option) {
+        Object.keys(validator.options).forEach(function(option) {
+            var data = validator.options[option];
             if (!data.allowedValues) {
@@ -60,13 +61,12 @@ return;
 
-            var values;
-            if (typeof data.allowedValues === 'function') {
-                values = data.allowedValues();
+            var values = data.allowedValues;
+            if (typeof values === 'function') {
+                values = values();
             }
 
-            if (!Array.isArray(values)) {
-                throw new Error('Internal error in jsDoc validator ' + validator._name);
+            assert(Array.isArray(values), 'Internal error in jsDoc validator ' + validator._name);
 
-            } else if (values.length > 1) {
+            if (values.length > 1) {
                 assert(values.indexOf(options[option]) !== -1,
-                    'Available values for option jsDoc.' + option + ' are ' + values.map(JSON.stringify).join(', '));
+                    'Accepted values for option jsDoc.' + option + ' are ' + values.map(JSON.stringify).join(', '));
 
@@ -73,0 +73,0 @@ } else if (values.length) {

package.json

@@ -5,3 +5,3 @@ {
   "description": "JSCS jsdoc plugin",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "main": "lib/index",
@@ -8,0 +8,0 @@ "homepage": "https://github.com/jscs-dev/jscs-jsdoc",

README.md

@@ -6,11 +6,16 @@ # jscs-jsdoc
 
-`jsdoc` plugin for [jscs](https://github.com/jscs-dev/node-jscs/).
+`jsdoc` plugin for [jscs](https://github.com/jscs-dev/node-jscs/). [Twitter](https://twitter.com/jscs_dev) | [Mailing List](https://groups.google.com/group/jscs-dev)
 
-## Friendly packages
+## Table of Contents
 
- * JSCS: https://github.com/jscs-dev/node-jscs/
+- [Installation](#plugin-installation)
+- [Versioning & Semver](#versioning--semver)
+- [Usage](#usage)
+- [Rules](#rules)
+- [Browser Usage](#browser-usage)
 
 ## Plugin installation
 
-`jscs-jsdoc` can be installed using `npm`.
+`jscs-jsdoc` can be installed using NPM and requires [jscs](https://github.com/jscs-dev/node-jscs/#installation).
+
 Install it globally if you are using globally installed `jscs`
@@ -24,5 +29,25 @@
 
+## Versioning & Semver
+
+We recommend installing `jscs-jsdoc` via NPM using `^`, or `~` if you want more stable releases.
+
+Semver (http://semver.org/) dictates that breaking changes be major version bumps. In the context of a linting tool, a bug fix that causes more errors to be reported can be interpreted as a breaking change. However, that would require major version bumps to occur more often than can be desirable. Therefore, as a compromise, we will only release bug fixes that cause more errors to be reported in minor versions.
+
+Below you fill find our versioning strategy, and what you can expect to come out of a new `jscs-jsdoc` release.
+
+ * Patch release:
+   * A bug fix in a rule that causes `jscs-jsdoc` to report less errors;
+   * Docs, refactoring and other "invisible" changes for user;
+ * Minor release:
+   * Any preset changes;
+   * A bug fix in a rule that causes `jscs-jsdoc` to report more errors;
+   * New rules or new options for existing rules that don't change existing behavior;
+   * Modifying rules so they report less errors, and don't cause build failures;
+ * Major release:
+   * Purposefully modifying existing rules so that they report more errors or change the meaning of a rule;
+   * Any architectural changes that could cause builds to fail.
+
 ## Usage
 
-To use plugin you should add it to configuration file `.jscsrc`:
+To use plugin you should add these lines to configuration file `.jscsrc`:
 
@@ -35,2 +60,3 @@ ```json
     "jsDoc": {
+        "enforceExistence": true
     }
@@ -40,38 +66,20 @@ }
 
-## Configuration
+## Rules
 
-### jsDoc
+### checkParamNames
 
-Enables JsDoc validation.
+Ensures param names in jsdoc and in function declaration are equal
 
-Type: `Object`
+Type: `Boolean`
 
-Values:
+Values: `true`
 
- - "checkParamNames" ensures param names in jsdoc and in function declaration are equal
- - "requireParamTypes" ensures params in jsdoc contains type
- - "checkRedundantParams" reports redundant params in jsdoc
- - "checkReturnTypes" tries to compare function result type with declared type in jsdoc
- - "requireReturnTypes" ensures returns in jsdoc contains type
- - "checkTypes" reports invalid types
- - "checkRedundantReturns" reports redundant returns in jsdoc
- - "checkRedundantAccess" reports redundant access declarations
- - "leadingUnderscoreAccess" ensures access declaration is set for `_underscored` function names
- - "enforceExistence" ensures jsdoc declarations exists for functions and methods
+Context: `functions`
 
+Tags: `param`, `arg`, `argument`
+
 #### Example
 
 ```js
-"jsDoc": {
-    "checkParamNames": true,
-    "checkRedundantParams": true,
-    "requireParamTypes": true,
-    "checkReturnTypes": true,
-    "requireReturnTypes": true,
-    "checkTypes": true,
-    "checkRedundantReturns": true,
-    "checkRedundantAccess": true,
-    "leadingUnderscoreAccess": "private",
-    "enforceExistence": true
-}
+"checkParamNames": true
 ```
@@ -83,13 +91,6 @@
 /**
- * Adds style error to the list
- *
- * @private
  * @param {String} message
- * @param {Number|Object} line
- * @param {Number} [column]
- * @returns {String[]}
+ * @param {Number|Object} [line]
  */
-_add: function(message, line, column) {
-    return ['foo', 'bar'];
-}
+function method(message, line) {}
 ```
@@ -101,18 +102,363 @@
 /**
- * Adds style error to the list
- *
- * @protected
+ * @param {String} msg
+ * @param {Number|Object} [line]
+ */
+function method(message) {}
+```
+
+### requireParamTypes
+
+Ensures params in jsdoc contains type
+
+Type: `Boolean`
+
+Values: `true`
+
+Context: `functions`
+
+Tags: `param`, `arg`, `argument`
+
+#### Example
+
+```js
+"requireParamTypes": true
+```
+
+##### Valid
+
+```js
+/**
  * @param {String} message
- * @param {Number,Object} line
- * @param {Number} [column]
+ */
+function method() {}
+```
+
+##### Invalid
+
+```js
+/**
+ * @param message
+ */
+function method() {}
+```
+
+### checkRedundantParams
+
+Reports redundant params in jsdoc
+
+Type: `Boolean`
+
+Values: `true`
+
+Context: `functions`
+
+Tags: `param`, `arg`, `argument`
+
+#### Example
+
+```js
+"checkRedundantParams": true
+```
+
+##### Valid
+
+```js
+/**
+ * @param {String} message
+ */
+function method(message) {}
+```
+
+##### Invalid
+
+```js
+/**
+ * @param {String} message
+ */
+function method(message) {}
+```
+
+### checkReturnTypes
+
+Reports discrepancies between the claimed in jsdoc and actual type if both exist (code scan)
+
+Type: `Boolean`
+
+Values: `true`
+
+Context: `functions`
+
+Tags: `return`, `returns`
+
+#### Example
+
+```js
+"checkReturnTypes": true
+```
+
+##### Valid
+
+```js
+/**
  * @returns {String}
  */
-_add: function() {
-    if (true) {
-        return false;
+function method() {
+    return 'foo';
+}
+```
+
+##### Invalid
+
+```js
+/**
+ * @returns {String}
+ */
+function method(f) {
+    if (f) {
+        return true;
     }
-    return 15;
+    return 1;
 }
 ```
 
+### checkRedundantReturns
+
+Report statements for functions with no return
+
+Type: `Boolean`
+
+Values: `true`
+
+Context: `functions`
+
+Tags: `return`, `returns`
+
+#### Example
+
+```js
+"checkRedundantReturns": true
+```
+
+##### Valid
+
+```js
+/**
+ * @returns {string}
+ */
+function f() {
+    return 'yes';
+}
+```
+
+##### Invalid
+
+```js
+/**
+ * @returns {string}
+ */
+function f() {
+    // no return here
+}
+```
+
+### requireReturnTypes
+
+Ensures returns in jsdoc contains type
+
+Type: `Boolean`
+
+Values: `true`
+
+Context: `functions`
+
+Tags: `return`, `returns`
+
+#### Example
+
+```js
+"requireReturnTypes": true
+```
+
+##### Valid
+
+```js
+/**
+ * @returns {String}
+ */
+function method() {}
+
+/**
+ * no @return
+ */
+function method() {}
+```
+
+##### Invalid
+
+```js
+/**
+ * @returns
+ */
+function method() {}
+```
+
+### checkTypes
+
+Reports invalid types for bunch of tags
+
+Type: `Boolean`
+
+Values: `true`
+
+Context: `*`
+
+Tags: `typedef`, `type`, `param`, `return`, `returns`, `enum`, `var`, `prop`, `property`, `arg`, `argument`, `cfg`, `lends`, `extends`, `implements`, `define`
+
+#### Example
+
+```js
+"checkTypes": true
+```
+
+##### Valid
+
+```js
+/**
+ * @typedef {Object} ObjectLike
+ * @property {boolean} hasFlag
+ * @property {string} name
+ */
+
+/** @type {number} */
+var bar = 1;
+
+/** @const {number} */
+var FOO = 2;
+
+/**
+ * @const
+ * @type {number}
+ */
+var BAZ = 3;
+
+/**
+ * @param {SomeX} x
+ * @returns {string}
+ */
+function method(x) {}
+```
+
+##### Invalid
+
+```js
+/** @type {some~number} */
+var x = 1;
+```
+
+### checkRedundantAccess
+
+Reports redundant access declarations
+
+Type: `Boolean`
+
+Values: `true`
+
+Context: `functions`
+
+Tags: `access`, `private`, `protected`, `public`
+
+#### Example
+
+```js
+"checkRedundantAccess": true
+```
+
+##### Valid
+
+```js
+/**
+ * @access private
+ */
+function _f() {}
+```
+
+##### Invalid
+
+```js
+/**
+ * @private
+ * @access private
+ */
+function _f() {}
+```
+
+### leadingUnderscoreAccess
+
+Ensures access declaration is set for `_underscored` function names
+
+Type: `Boolean` or `String`
+
+Values: `true` (means not public), `"private"`, `"protected"`
+
+Context: `functions`
+
+Tags: `access`, `private`, `protected`, `public`
+
+#### Example
+
+```js
+"checkRedundantAccess": "protected"
+```
+
+##### Valid
+
+```js
+/**
+ * @protected
+ */
+function _f() {}
+```
+
+##### Invalid
+
+```js
+function _g() {}
+
+/**
+ * @private
+ */
+function _e() {}
+```
+
+### enforceExistence
+
+Ensures jsdoc block exist
+
+Type: `Boolean`
+
+Values: `true`
+
+Context: `functions`
+
+#### Example
+
+```js
+"enforceExistence": true
+```
+
+##### Valid
+
+```js
+/**
+ * @protected
+ */
+function _f() {}
+```
+
+##### Invalid
+
+```js
+function _g() {}
+```
+
 ## Browser Usage
@@ -119,0 +465,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

39265

increased by15.38%

Lines of code

895

increased by2.87%

Number of lines in readme file

479

increased by260.15%

No dependency changes