Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

jscs-jsdoc

Package Overview
Dependencies
Maintainers
1
Versions
42
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

jscs-jsdoc

JSCS jsdoc plugin

  • 0.0.24
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
38K
decreased by-2.25%
Maintainers
1
Weekly downloads
 
Created
Source

jscs-jsdoc

Build Status NPM version Dependency Status

jsdoc plugin for jscs. Twitter | Mailing List

Table of Contents

Plugin installation

jscs-jsdoc can be installed using NPM and requires jscs.

Install it globally if you are using globally installed jscs

npm -g install jscs-jsdoc

But better install it into your project

npm install jscs-jsdoc --save-dev

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 these lines to configuration file .jscsrc:

{
    "additionalRules": [
        "node_modules/jscs-jsdoc/lib/rules/*.js"
    ],
    "jsDoc": {
        "enforceExistence": true
    }
}

Rules

checkParamNames

Ensures param names in jsdoc and in function declaration are equal

Type: Boolean

Values: true

Context: functions

Tags: param, arg, argument

Example
"checkParamNames": true
Valid
/**
 * @param {String} message
 * @param {Number|Object} [line]
 */
function method(message, line) {}
Invalid
/**
 * @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
"requireParamTypes": true
Valid
/**
 * @param {String} message
 */
function method() {}
Invalid
/**
 * @param message
 */
function method() {}

checkRedundantParams

Reports redundant params in jsdoc

Type: Boolean

Values: true

Context: functions

Tags: param, arg, argument

Example
"checkRedundantParams": true
Valid
/**
 * @param {String} message
 */
function method(message) {}
Invalid
/**
 * @param {String} message
 */
function method() {}

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
"checkReturnTypes": true
Valid
/**
 * @returns {String}
 */
function method() {
    return 'foo';
}
Invalid
/**
 * @returns {String}
 */
function method(f) {
    if (f) {
        return true;
    }
    return 1;
}

checkRedundantReturns

Report statements for functions with no return

Type: Boolean

Values: true

Context: functions

Tags: return, returns

Example
"checkRedundantReturns": true
Valid
/**
 * @returns {string}
 */
function f() {
    return 'yes';
}
Invalid
/**
 * @returns {string}
 */
function f() {
    // no return here
}

requireReturnTypes

Ensures returns in jsdoc contains type

Type: Boolean

Values: true

Context: functions

Tags: return, returns

Example
"requireReturnTypes": true
Valid
/**
 * @returns {String}
 */
function method() {}

/**
 * no @return
 */
function method() {}
Invalid
/**
 * @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
"checkTypes": true
Valid
/**
 * @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
/** @type {some~number} */
var x = 1;

checkRedundantAccess

Reports redundant access declarations

Type: Boolean

Values: true

Context: functions

Tags: access, private, protected, public

Example
"checkRedundantAccess": true
Valid
/**
 * @access private
 */
function _f() {}
Invalid
/**
 * @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
"checkRedundantAccess": "protected"
Valid
/**
 * @protected
 */
function _f() {}
Invalid
function _g() {}

/**
 * @private
 */
function _e() {}

enforceExistence

Ensures jsdoc block exist

Type: Boolean

Values: true

Context: functions

Example
"enforceExistence": true
Valid
/**
 * @protected
 */
function _f() {}
Invalid
function _g() {}

requireHyphenBeforeDescription

Ensures a param description has a hyphen before it (checks for - )

Type: Boolean

Values: true

Context: functions

Tags: param, arg, argument

Example
"requireHyphenBeforeDescription": true
Valid
/**
 * @param {String} - message
 */
function method() {}
Invalid
/**
 * @param {String} message
 */
function method() {}

Browser Usage

NOT SUPPORTED ATM. SORRY.

File jscs-jsdoc-browser.js contains browser-compatible version of jscs-jsdoc.

Download and include jscs-jsdoc-browser.js into your page just after jscs-browser.js.

<script src="jscs-browser.js"></script>
<script src="jscs-jsdoc-browser.js"></script>
<script>
    var checker = new JscsStringChecker();
    checker.registerDefaultRules();
    checker.configure({'jsDoc': {/* ... */}});
    var errors = checker.checkString('var x, y = 1;');
    errors.getErrorList().forEach(function (error) {
        console.log(errors.explainError(error));
    });
</script>

FAQs

Package last updated on 18 Nov 2014

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc