<commit_before># jscs-jsdoc
[![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/jscs-dev/jscs-jsdoc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Build Status](https://secure.travis-ci.org/jscs-dev/jscs-jsdoc.svg?branch=master)](http://travis-ci.org/jscs-dev/jscs-jsdoc)
[![NPM version](https://badge.fury.io/js/jscs-jsdoc.png)](http://badge.fury.io/js/jscs-jsdoc)
[![Dependency Status](https://david-dm.org/jscs-dev/jscs-jsdoc.png)](https://david-dm.org/jscs-dev/jscs-jsdoc)

`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)

## Table of Contents

- [Installation](#plugin-installation)
- [Versioning & Semver](#versioning--semver)
- [Usage](#usage)
- [Rules](#rules)
- [Browser Usage](#browser-usage)

## Plugin installation

`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`

    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`:

```json
{
    "plugins": [
        "jscs-jsdoc"
    ],
    "jsDoc": {
        "checkAnnotations": "closurecompiler",
        "checkTypes": "strictNativeCase",
        "enforceExistence": "exceptExports"
    }
}
```

## Rules

### checkAnnotations

Ensures tag names are valid

There are 3 presets for `Closure Compiler`, `JSDoc3` and `JSDuck5`.

By 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.

Type: `Boolean` or `String` or `{"preset": String, "extra": Object}` (`extra` field should contains tags in keys and boolean in values. false means no value possible)

Values: `true`, `"closurecompiler"`, `"jsdoc3"`, `"jsduck5"`, `Object`

Context: `file`

Tags: `*`

#### Example

```js
"checkAnnotations": true
```

##### Valid

```js
/**
 * @chainable
 * @param {string} message
 * @return {string}
 */
function _f() {}
```
<commit_msg>Docs: update tag values section<commit_after># jscs-jsdoc
[![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/jscs-dev/jscs-jsdoc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Build Status](https://secure.travis-ci.org/jscs-dev/jscs-jsdoc.svg?branch=master)](http://travis-ci.org/jscs-dev/jscs-jsdoc)
[![NPM version](https://badge.fury.io/js/jscs-jsdoc.png)](http://badge.fury.io/js/jscs-jsdoc)
[![Dependency Status](https://david-dm.org/jscs-dev/jscs-jsdoc.png)](https://david-dm.org/jscs-dev/jscs-jsdoc)

`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)

## Table of Contents

- [Installation](#plugin-installation)
- [Versioning & Semver](#versioning--semver)
- [Usage](#usage)
- [Rules](#rules)
- [Browser Usage](#browser-usage)

## Plugin installation

`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`

    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`:

```json
{
    "plugins": [
        "jscs-jsdoc"
    ],
    "jsDoc": {
        "checkAnnotations": "closurecompiler",
        "checkTypes": "strictNativeCase",
        "enforceExistence": "exceptExports"
    }
}
```

## Rules

### checkAnnotations

Ensures tag names are valid

There are 3 presets for `Closure Compiler`, `JSDoc3` and `JSDuck5`.

By 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.

Type: `Boolean` or `String` or `{"preset": String, "extra": Object}` (see [tag values](#user-content-tag-values))

Values: `true`, `"closurecompiler"`, `"jsdoc3"`, `"jsduck5"`, `Object`

Context: `file`

Tags: `*`

#### Tag values

`extra` field should contains tags in keys and there are options for values:
- `false` means tag available with no value
- `true` means tag available with any value
- `"some"` means tag available and requires some value

See also [tag presets](https://github.com/jscs-dev/jscs-jsdoc/tree/hotfix/check-annotations-rework/lib/tags).

#### Example

```js
"checkAnnotations": true
```

##### Valid

```js
/**
 * @chainable
 * @param {string} message
 * @return {string}
 */
function _f() {}
```

{'fraction_non_alphanumeric': 0.13047068538398018, 'fraction_numerical': 0.0013762730525736307, 'mean_word_length': 4.183309557774607, 'pattern_counts': {'":': 16, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 21, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3559142', 'n_tokens_mistral': 2441, 'n_tokens_neox': 2354, 'n_words': 784}