{"name":"jscs-jsdoc","author":{"name":"Alexej Yaroshevich","email":"alex@qfox.ru"},"description":"JSCS jsdoc plugin","version":"1.2.0","main":"lib/index","homepage":"https://github.com/jscs-dev/jscs-jsdoc","license":"MIT","repository":{"type":"git","url":"https://github.com/jscs-dev/jscs-jsdoc"},"bugs":{"url":"https://github.com/jscs-dev/jscs-jsdoc/issues"},"contributors":[{"name":"Alexej Yaroshevich","email":"alex@qfox.ru"},{"name":"Henry Zhu","email":"hi@henryzoo.com"},{"name":"Christopher Hiller","email":"chiller@badwing.com"},{"name":"Raphael Pigulla","email":"raphael.pigulla@tngtech.com"}],"engines":{"node":">= 0.10.0"},"dependencies":{"comment-parser":"0.3.0","jsdoctypeparser":"~1.2.0"},"devDependencies":{"chai":"^2.3.0","chai-subset":"^1.1.0","jscs":"^2.1.1","jshint":"^2.7.0","mocha":"^2.2.4"},"_peerDependencies":{"jscs":">=1.8.0 <2.0"},"scripts":{"lint":"jshint lib test && jscs lib test","test":"npm run lint && mocha","browserify":"browserify --standalone JsdocJscsPlugin lib/index.js -o jscs-jsdoc-browser.js","changelog":"changelog-maker jscs-dev jscs-jsdoc --group"},"files":["lib","LICENSE"],"licenses":[{"type":"MIT","url":"http://github.com/jscs-dev/jscs-jsdoc/raw/master/LICENSE"}],"readme":"# jscs-jsdoc\n[![Gitter](https://img.shields.io/badge/GITTER-JOIN_CHAT_%E2%86%92-1dce73.svg)](https://gitter.im/jscs-dev/talks?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)\n[![Build Status](https://img.shields.io/travis/jscs-dev/jscs-jsdoc.svg)](http://travis-ci.org/jscs-dev/jscs-jsdoc?style=flat)\n[![Dependency Status](https://img.shields.io/david/jscs-dev/jscs-jsdoc.svg)](https://david-dm.org/jscs-dev/jscs-jsdoc)\n[![Coverage](https://img.shields.io/coveralls/jscs-dev/jscs-jsdoc.svg)](https://coveralls.io/r/jscs-dev/jscs-jsdoc)\n\n[![NPM version](https://img.shields.io/npm/v/jscs-jsdoc.svg)](https://www.npmjs.com/package/jscs-jsdoc)\n[![NPM downloads](https://img.shields.io/npm/dm/jscs-jsdoc.svg)](https://www.npmjs.com/package/jscs-jsdoc)\n[![MIT License](https://img.shields.io/npm/l/jscs-jsdoc.svg)](https://github.com/jscs-dev/jscs-jsdoc/blob/master/LICENSE)\n\n`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)\n\n## Table of Contents\n\n- [Installation](#plugin-installation)\n- [Versioning & Semver](#versioning--semver)\n- [Usage](#usage)\n- [Rules](#rules)\n- [Browser Usage](#browser-usage)\n\n## Plugin installation\n\n`jscs-jsdoc` can be installed using NPM and requires [jscs](https://github.com/jscs-dev/node-jscs/#installation).\n\nInstall it globally if you are using globally installed `jscs`\n\n    npm -g install jscs-jsdoc\n\nBut better install it into your project\n\n    npm install jscs-jsdoc --save-dev\n\n## Versioning & Semver\n\nWe recommend installing `jscs-jsdoc` via NPM using `^`, or `~` if you want more stable releases.\n\nSemver (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.\n\nBelow you fill find our versioning strategy, and what you can expect to come out of a new `jscs-jsdoc` release.\n\n * Patch release:\n   * A bug fix in a rule that causes `jscs-jsdoc` to report less errors;\n   * Docs, refactoring and other \"invisible\" changes for user;\n * Minor release:\n   * Any preset changes;\n   * A bug fix in a rule that causes `jscs-jsdoc` to report more errors;\n   * New rules or new options for existing rules that don't change existing behavior;\n   * Modifying rules so they report less errors, and don't cause build failures;\n * Major release:\n   * Purposefully modifying existing rules so that they report more errors or change the meaning of a rule;\n   * Any architectural changes that could cause builds to fail.\n\n## Usage\n\nTo use plugin you should add these lines to configuration file `.jscsrc`:\n\n```json\n{\n    \"plugins\": [\n        \"jscs-jsdoc\"\n    ],\n    \"jsDoc\": {\n        \"checkAnnotations\": \"closurecompiler\",\n        \"checkTypes\": \"strictNativeCase\",\n        \"enforceExistence\": \"exceptExports\"\n    }\n}\n```\n\n## Rules\n\n### checkAnnotations\n\nEnsures tag names are valid\n\nThere are 3 presets for `Closure Compiler`, `JSDoc3` and `JSDuck5`.\n\nBy default it allows any tag of mixed set. You can pass `Object` to select preset with `preset` field and add custom tags with `extra` field.\n\nType: `Boolean` or `String` or `{\"preset\": String, \"extra\": Object}` (see [tag values](#user-content-tag-values))\n\nValues: `true`, `\"closurecompiler\"`, `\"jsdoc3\"`, `\"jsduck5\"`, `Object`\n\nContext: `file`\n\nTags: `*`\n\n#### Tag values\n\n`extra` field should contains tags in keys and there are options for values:\n- `false` means tag available with no value\n- `true` means tag available with any value\n- `\"some\"` means tag available and requires some value\n\nSee also [tag presets](https://github.com/jscs-dev/jscs-jsdoc/tree/master/lib/tags).\n\n#### Example\n\n```js\n\"checkAnnotations\": true\n```\n\n##### Valid\n\n```js\n/**\n * @chainable\n * @param {string} message\n * @return {string}\n */\nfunction _f() {}\n```\n\n##### Invalid\n\n```js\n/**\n * @pororo\n * @lalala\n */\nfunction _f() {}\n```\n\n#### Example 2\n\n```js\n\"checkAnnotations\": {\n    \"preset\": \"jsdoc3\",\n    \"extra\": {\n        \"boomer\": false\n    }\n}\n```\n\n##### Valid\n\n```js\n/**\n * @boomer\n * @argument {String}\n */\nfunction _f() {}\n```\n\n##### Invalid\n\n```js\n/** @still-invalid */\n```\n\n### checkParamExistence\n\nEnsures all parameters are documented.\n\nType: `Boolean`\n\nValues: `true`\n\n\n#### Example\n\n```js\n\"checkParamExistence\": true\n```\n\n##### Valid\n\n```js\n/**\n * @param {string} message\n * @return {string}\n */\nfunction _f ( message ) {\n  return true;\n}\n\n/**\n * @inheritdoc\n */\nfunction _f ( message ) {\n  return true;\n}\n```\n\n##### Invalid\n\n```js\n/**\n * @return {string}\n */\nfunction _f ( message ) {\n  return true;\n}\n```\n\n### checkParamNames\n\nEnsures param names in jsdoc and in function declaration are equal\n\nType: `Boolean`\n\nValues: `true`\n\nContext: `functions`\n\nTags: `param`, `arg`, `argument`\n\n#### Example\n\n```js\n\"checkParamNames\": true\n```\n\n##### Valid\n\n```js\n/**\n * @param {String} message\n * @param {Number|Object} [line]\n */\nfunction method(message, line) {}\n```\n\n##### Invalid\n\n```js\n/**\n * @param {String} msg\n * @param {Number|Object} [line]\n */\nfunction method(message) {}\n```\n\n### requireParamTypes\n\nEnsures params in jsdoc contains type\n\nType: `Boolean`\n\nValues: `true`\n\nContext: `functions`\n\nTags: `param`, `arg`, `argument`\n\n#### Example\n\n```js\n\"requireParamTypes\": true\n```\n\n##### Valid\n\n```js\n/**\n * @param {String} message\n */\nfunction method() {}\n```\n\n##### Invalid\n\n```js\n/**\n * @param message\n */\nfunction method() {}\n```\n\n### checkRedundantParams\n\nReports redundant params in jsdoc\n\nType: `Boolean`\n\nValues: `true`\n\nContext: `functions`\n\nTags: `param`, `arg`, `argument`\n\n#### Example\n\n```js\n\"checkRedundantParams\": true\n```\n\n##### Valid\n\n```js\n/**\n * @param {String} message\n */\nfunction method(message) {}\n```\n\n##### Invalid\n\n```js\n/**\n * @param {String} message\n */\nfunction method() {}\n```\n\n### checkReturnTypes\n\nReports discrepancies between the claimed in jsdoc and actual type if both exist (code scan)\n\nType: `Boolean`\n\nValues: `true`\n\nContext: `functions`\n\nTags: `return`, `returns`\n\n#### Example\n\n```js\n\"checkReturnTypes\": true\n```\n\n##### Valid\n\n```js\n/**\n * @returns {String}\n */\nfunction method() {\n    return 'foo';\n}\n```\n\n##### Invalid\n\n```js\n/**\n * @returns {String}\n */\nfunction method(f) {\n    if (f) {\n        return true;\n    }\n    return 1;\n}\n```\n\n### checkRedundantReturns\n\nReport statements for functions with no return\n\nType: `Boolean`\n\nValues: `true`\n\nContext: `functions`\n\nTags: `return`, `returns`\n\n#### Example\n\n```js\n\"checkRedundantReturns\": true\n```\n\n##### Valid\n\n```js\n/**\n * @returns {string}\n */\nfunction f() {\n    return 'yes';\n}\n```\n\n##### Invalid\n\n```js\n/**\n * @returns {string}\n */\nfunction f() {\n    // no return here\n}\n```\n\n### requireReturnTypes\n\nEnsures returns in jsdoc contains type\n\nType: `Boolean`\n\nValues: `true`\n\nContext: `functions`\n\nTags: `return`, `returns`\n\n#### Example\n\n```js\n\"requireReturnTypes\": true\n```\n\n##### Valid\n\n```js\n/**\n * @returns {String}\n */\nfunction method() {}\n\n/**\n * no @return\n */\nfunction method() {}\n```\n\n##### Invalid\n\n```js\n/**\n * @returns\n */\nfunction method() {}\n```\n\n### checkTypes\n\nReports invalid types for bunch of tags\n\nIn `strictNativeCase` mode ensures that case of natives is the same as in this list: `boolean`, `number`, `string`, `Object`, `Array`, `Date`, `RegExp`.\n\nIn `capitalizedNativeCase` mode ensures that first letter in all native types and primitives is uppercased except the case with `function` in google closure format: `{function(...)}`\n\nType: `Boolean` or `String`\n\nValues: `true` or `\"strictNativeCase\"` or `\"capitalizedNativeCase\"`\n\nContext: `*`\n\nTags: `typedef`, `type`, `param`, `return`, `returns`, `enum`, `var`, `prop`, `property`, `arg`, `argument`, `cfg`, `lends`, `extends`, `implements`, `define`\n\n#### Example\n\n```js\n\"checkTypes\": true\n```\n\n##### Valid\n\n```js\n/**\n * @typedef {Object} ObjectLike\n * @property {boolean} hasFlag\n * @property {string} name\n */\n\n/** @type {number} */\nvar bar = 1;\n\n/** @const {number} */\nvar FOO = 2;\n\n/**\n * @const\n * @type {number}\n */\nvar BAZ = 3;\n\n/**\n * @param {SomeX} x\n * @returns {string}\n */\nfunction method(x) {}\n```\n\n##### Invalid\n\n```js\n/** @type {some~number} */\nvar x = 1;\n\n/**\n * @param {function(redundantName: Number)} x\n */\nfunction method(x) {}\n\n/**\n * @param {Number|Boolean|object|array} x invalid for strictNativeCase\n */\nfunction method(x) {}\n```\n\n```js\n/** @type {some~number} */\nvar x = 1;\n```\n\n### checkRedundantAccess\n\nReports redundant access declarations\n\nType: `Boolean` or `String`\n\nValues: `true` or `\"enforceLeadingUnderscore\"` or `\"enforceTrailingUnderscore\"`\n\nContext: `functions`\n\nTags: `access`, `private`, `protected`, `public`\n\n#### Example\n\n```js\n\"checkRedundantAccess\": true\n\"checkRedundantAccess\": \"enforceLeadingUnderscore\"\n```\n\n##### Valid for true, \"enforceLeadingUnderscore\"\n\n```js\n/**\n * @access private\n */\nfunction _f() {}\n\n/**\n * @access public\n */\nfunction f() {}\n```\n\n##### Invalid for true\n\n```js\n/**\n * @private\n * @access private\n */\nfunction _f() {}\n```\n\n##### Invalid for \"enforceLeadingUnderscore\"\n\n```js\n/**\n * @private\n */\nfunction _f() {}\n```\n\n### leadingUnderscoreAccess\n\nEnsures access declaration is set for `_underscored` function names\n\nIgnores a bunch of popular identifiers: `__filename`, `__dirname`, `__proto__`, `__defineGetter__`, `super_`, `__constructor`, etc.\n\nType: `Boolean` or `String`\n\nValues: `true` (means not public), `\"private\"`, `\"protected\"`\n\nContext: `functions`\n\nTags: `access`, `private`, `protected`, `public`\n\n#### Example\n\n```js\n\"leadingUnderscoreAccess\": \"protected\"\n```\n\n##### Valid\n\n```js\n/**\n * @protected\n */\nfunction _f() {}\n```\n\n##### Invalid\n\n```js\nfunction _g() {}\n\n/**\n * @private\n */\nfunction _e() {}\n```\n\n### enforceExistence\n\nEnsures jsdoc block exist\n\nType: `Boolean`, `String` or `Object`\n\nValues:\n- `true`\n- `\"exceptExports\"` (*deprecated* use `\"allExcept\": [\"exports\"]`)\n- `Object`:\n  - `\"allExcept\"` array of exceptions:\n    - `\"expressions\"` skip expression functions\n    - `\"exports\"` skip `module.exports = function () {};`\n    - `\"paramless-procedures\"` functions without parameters and with empty return statements will be skipped\n\nContext: `functions`\n\n#### Example\n\n```js\n\"enforceExistence\": true\n```\n\n##### Valid\n\n```js\n/**\n * @protected\n */\nfunction _f() {}\n```\n\n##### Invalid\n\n```js\nfunction _g() {}\n```\n\n\n### requireHyphenBeforeDescription\n\nEnsures a param description has a hyphen before it (checks for `- `)\n\nType: `Boolean`\n\nValues: `true`\n\nContext: `functions`\n\nTags: `param`, `arg`, `argument`\n\n#### Example\n\n```js\n\"requireHyphenBeforeDescription\": true\n```\n\n##### Valid\n\n```js\n/**\n * @param {String} - message\n */\nfunction method() {}\n```\n\n##### Invalid\n\n```js\n/**\n * @param {String} message\n */\nfunction method() {}\n```\n\n\n### requireNewlineAfterDescription\n\nEnsures a doc comment description has padding newline\n\nType: `Boolean`\n\nValues: `true`\n\nContext: `functions`\n\nTags: `*`\n\n#### Example\n\n```js\n\"requireNewlineAfterDescription\": true\n```\n\n##### Valid\n\n```js\n/**\n * @param {String} - message\n */\nfunction method() {}\n\n/**\n * Description\n */\nfunction method() {}\n\n/**\n * Description\n *\n * @param {String} - message\n */\nfunction method() {}\n```\n\n##### Invalid\n\n```js\n/**\n * Description\n * @param {String} message\n */\nfunction method() {}\n```\n\n\n### disallowNewlineAfterDescription\n\nEnsures a doc comment description has no padding newlines\n\nType: `Boolean`\n\nValues: `true`\n\nContext: `functions`\n\nTags: `*`\n\n#### Example\n\n```js\n\"disallowNewlineAfterDescription\": true\n```\n\n##### Valid\n\n```js\n/**\n * @param {String} - message\n */\nfunction method() {}\n\n/**\n * Description\n */\nfunction method() {}\n\n/**\n * Description\n * @param {String} - message\n */\nfunction method() {}\n```\n\n##### Invalid\n\n```js\n/**\n * Description\n *\n * @param {String} message\n */\nfunction method() {}\n```\n\n\n### requireDescriptionCompleteSentence\n\nEnsures a doc comment description is a complete sentence.\n\nA complete sentence is defined as starting with an upper case letter and ending with a period.\n\nType: `Boolean`\n\nValues: `true`\n\nContext: `functions`\n\nTags: `*`\n\n#### Example\n\n```js\n\"requireDescriptionCompleteSentence\": true\n```\n\n##### Valid\n\n```js\n/**\n * @param {String} - message\n */\nfunction method() {}\n\n/**\n * Description.\n */\nfunction method() {}\n\n/**\n * (Description).\n */\nfunction method() {}\n\n/**\n * Description.\n *\n * @param {String} - message\n */\nfunction method() {}\n\n/**\n * Description\n * On multiple lines.\n *\n * @param {String} - message\n */\nfunction method() {}\n```\n\n##### Invalid\n\n```js\n/**\n * Description\n * @param {String} message\n */\nfunction method() {}\n\n/**\n * description starting with a lower case letter.\n * @param {String} message\n */\nfunction method() {}\n\n/**\n * Description period is offset .\n * @param {String} message\n */\nfunction method() {}\n\n/**\n * Description!\n * @param {String} message\n */\nfunction method() {}\n```\n\n\n### requireParamDescription\n\nEnsures a param description exists.\n\nType: `Boolean`\n\nValues: `true`\n\nContext: `functions`\n\nTags: `param`, `arg`, `argument`\n\n#### Example\n\n```js\n\"requireParamDescription\": true\n```\n\n##### Valid\n\n```js\n/**\n * @param {String} arg message\n */\nfunction method(arg) {}\n\n/**\n * @param arg message\n */\nfunction method(arg) {}\n```\n\n##### Invalid\n\n```js\n/**\n * @param {String} arg\n */\nfunction method(arg) {}\n\n/**\n * @param arg\n */\nfunction method(arg) {}\n```\n\n\n### requireReturnDescription\n\nEnsures a return description exists.\n\nType: `Boolean`\n\nValues: `true`\n\nContext: `functions`\n\nTags: `return`, `returns`\n\n#### Example\n\n```js\n\"requireReturnDescription\": true\n```\n\n##### Valid\n\n```js\n/**\n * @returns {Boolean} Method result.\n */\nfunction method() {\n  return false;\n}\n\n/**\n * @returns {String} method result\n */\nfunction method() {\n  return 'Hello!';\n}\n```\n\n##### Invalid\n\n```js\n/**\n * @returns {Boolean}\n */\nfunction method() {\n  return false;\n}\n```\n\n\n## Browser Usage\n\nNOT SUPPORTED ATM. SORRY.\n\nFile [jscs-jsdoc-browser.js](jscs-jsdoc-browser.js) contains browser-compatible version of `jscs-jsdoc`.\n\nDownload and include `jscs-jsdoc-browser.js` into your page just after `jscs-browser.js`.\n\n```html\n<script src=\"jscs-browser.js\"></script>\n<script src=\"jscs-jsdoc-browser.js\"></script>\n<script>\n    var checker = new JscsStringChecker();\n    checker.registerDefaultRules();\n    checker.configure({'jsDoc': {/* ... */}});\n    var errors = checker.checkString('var x, y = 1;');\n    errors.getErrorList().forEach(function (error) {\n        console.log(errors.explainError(error));\n    });\n</script>\n```\n","readmeFilename":"README.md","_id":"jscs-jsdoc@1.2.0","_shasum":"6a04048e8c8af4f6a3a97387a60b836a79cb1722","_from":"https://registry.npmjs.org/jscs-jsdoc/-/jscs-jsdoc-1.2.0.tgz","_resolved":"https://registry.npmjs.org/jscs-jsdoc/-/jscs-jsdoc-1.2.0.tgz"}