<commit_before># flow-jsdoc
[![Build Status](https://travis-ci.org/Kegsay/flow-jsdoc.svg?branch=master)](https://travis-ci.org/Kegsay/flow-jsdoc)

This is a CLI tool to convert [JSDoc](http://usejsdoc.org/index.html) annotations into standard [Flow](https://flowtype.org/) type annotations. This means:
 - You only need to document your types once: in JSDoc.
 - You can get the benefits of Flow without having to go through a [transpiler](http://babeljs.io/), and without having to use [ugly looking comment syntax](https://flowtype.org/blog/2015/02/20/Flow-Comments.html).

```javascript
// Converts this:

/**
 * @param {Foobar[]} bar A foobar array
 * @param {Function} baz
 * @return {number}
 */
function foo(bar, baz) {
    return 42;
}

// Into this:

/**
 * @param {Foobar[]} bar A foobar array
 * @param {Function} baz
 * @return {number}
 */
function foo(bar: Array<Foobar>, baz: Function) : number {
    return 42;
}
```

The goal of this project is to make type checking as easy as running a linter, so you can take any project and run the following to get type errors:
```
 $ flow-jsdoc -d ./lib -o ./annotated
 $ flow check --all ./annotated
```

# Usage

*This tool will NOT apply* `/* @flow */` *to the file. You still need to do that!*

## CLI
```
 $ npm install -g flow-jsdoc
 $ flow-jsdoc -f path/to/file.js
# annotated file prints to stdout

 $ flow-jsdoc -d path/to/lib -o path/to/output
# every file in path/to/lib is processed and output to path/to/output (directory structure preserved)
```

## JS
```javascript
 var flowJsdoc = require("flow-jsdoc");
 var fileContents = // extract your file contents e.g. via 'fs' - this should be a string
 var opts = {
 // no options yet!
 };<commit_msg>Mention inline comment style<commit_after># flow-jsdoc
[![Build Status](https://travis-ci.org/Kegsay/flow-jsdoc.svg?branch=master)](https://travis-ci.org/Kegsay/flow-jsdoc)

This is a CLI tool to convert [JSDoc](http://usejsdoc.org/index.html) annotations into standard [Flow](https://flowtype.org/) type annotations. This means:
 - You only need to document your types once: in JSDoc.
 - You can get the benefits of Flow without having to go through a [transpiler](http://babeljs.io/), and without having to use [ugly looking comment syntax](https://flowtype.org/blog/2015/02/20/Flow-Comments.html).
 - You can do tiny in-line type comments for those functions which don't have JSDoc but you still want types.

```javascript
// Converts this:

/**
 * @param {Foobar[]} bar A foobar array
 * @param {Function} baz
 * @return {number}
 */
function foo(bar, baz) {
    return 42;
}

// Into this:

/**
 * @param {Foobar[]} bar A foobar array
 * @param {Function} baz
 * @return {number}
 */
function foo(bar: Array<Foobar>, baz: Function) : number {
    return 42;
}
```

Furthermore, a short in-line style is also supported:

```js
// Converts this:

//: (string, number) : Object
function foo(a, b) {
  return {};
}

// Into this:

//: (string, number) : Object
function foo(a: string, b: number) : Object {
  return {};
}

// NB: The ":" at the start of the comment is REQUIRED.
```

The goal of this project is to make type checking as easy as running a linter, so you can take any project and run the following to get type errors:
```
 $ flow-jsdoc -d ./lib -o ./annotated
 $ flow check --all ./annotated
```

# Usage

*This tool will NOT apply* `/* @flow */` *to the file. You still need to do that!*

## CLI
```
 $ npm install -g flow-jsdoc
 $ flow-jsdoc -f path/to/file.js
# annotated file prints to stdout

 $ flow-jsdoc -d path/to/lib -o path/to/output
# every file in path/to/lib is processed and output to path/to/output (directory structure preserved)
```

## JS
```javascript
 var flowJsdoc = require("flow-jsdoc");
 var fileContents = // extract your file contents e.g. via 'fs' - this should be a string
 var opts = {
 // no options yet!
 };
{'fraction_non_alphanumeric': 0.14237726098191214, 'fraction_numerical': 0.006201550387596899, 'mean_word_length': 3.5011627906976743, 'pattern_counts': {'":': 1, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 8, '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': '33010', 'n_tokens_mistral': 1323, 'n_tokens_neox': 1248, 'n_words': 468}