Skip to content

Commit 51ca0e8

Browse files
75lb75lb
committed
readme
1 parent cb46a17 commit 51ca0e8

6 files changed

Lines changed: 63 additions & 50 deletions

File tree

‎README.md‎

Lines changed: 30 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -7,23 +7,14 @@
77
# jsdoc-parse
88
Jsdoc-annotated source code in, JSON format documentation out.
99

10-
Essentially, the output is the raw JSON output of [jsdoc](https://github.com/jsdoc3/jsdoc) with a few extras:
10+
jsdoc-parse extends [jsdoc](https://github.com/jsdoc3/jsdoc) with a few features:
1111

1212
* Support for html input files (see `--html` option).
1313
* Support for new tags in the input javascript
1414
* `@category <string>`: Useful for grouping identifiers by category.
1515
* `@done`: Used to mark `@todo` items as complete.
1616
* `@typicalname`: If set on a class, namespace or module, child members will documented using this typical name as the parent name. Real-world typical name examples are `$` (the typical name for `jQuery` instances), `_` (underscore) etc.
1717
* `@chainable`: Set to mark a method as chainable (has a return value of `this`).
18-
* Some new fields:
19-
* `id`: a unique identifier (the jsdoc `longname` field is not guaranteed unique)
20-
* `isExported`: set to true on the identifier which is exported from a module.
21-
* `todoList`: A list.
22-
* `typicalname`
23-
* `category`
24-
* `order`: The sort position of the identifier in the source file. Useful for use in `--sort-by` expressions.
25-
* A separate constructor record. In jsdoc, the class and constructor information are contained within the same record. In jsdoc-parse, the constructor information is separated from the class into a record with kind `"constructor"`.
26-
2718

2819
## Synopsis
2920
### Simple example
@@ -177,29 +168,36 @@ $ jsdoc-parse example/doc.html --html
177168

178169
## Install and use
179170

180-
### Compatible Platforms
181-
Tested on Mac OSX, Linux, Windows 8.1 and Windows XP.
182-
183171
### As a command-line tool
184172
Useful for quick access to the data..
185173

186174
```
187175
$ npm install -g jsdoc-parse
188176
$ jsdoc-parse --help
189177
190-
jsdoc-parse
191-
Jsdoc-annotated source code in, JSON format documentation out.
178+
jsdoc-parse
192179
193-
Usage
194-
$ jsdoc-parse <files>
195-
$ cat <files> | jsdoc-parse
180+
Jsdoc-annotated source code in, JSON format documentation out.
196181
197-
--private Include identifiers marked @private in the output
198-
--stats Print a few stats about the doclets parsed
199-
--html Enable experimental parsing of .html files
200-
--src <array> A list of javascript source files or glob expressions
201-
-s, --sort-by <array> Sort by one of more fields, e.g. `--sort-by kind category`. Defaults to 'scope kind'.
202-
-h, --help
182+
Synopsis
183+
184+
$ jsdoc-parse [-PH] [--sort-by fields] [--conf file] [--src file ...]
185+
$ jsdoc-parse --help
186+
$ jsdoc-parse --stats
187+
188+
Options
189+
190+
-f, --src file ... A list of javascript source files (or glob expressions) to parse for
191+
documentation. If this option is not set jsdoc-parse will wait for source
192+
code on stdin (i.e. `cat *.js | jsdoc-parse [options]`).
193+
-P, --private Include identifiers marked @private in the output
194+
-H, --html Enable experimental parsing of .html files
195+
--conf file Path to a jsdoc configuration file, passed directly to `jsdoc -c`.
196+
-s, --sort-by property ... Sort by one of more properties, e.g. `--sort-by kind category`. Defaults to
197+
`[ "scope", "category", "kind", "order" ]`. Pass the special value `none` to
198+
remove the default sort order.
199+
--stats Print a few stats about the doclets parsed
200+
-h, --help Display this usage.
203201
```
204202

205203
***Usage form 2 warning***: When piping input into `jsdoc-parse` it will intepret the whole of what is piped in as a single file, so take care not to pipe in input containing multipe @modules as this is illegal in jsdoc (see [here](http://usejsdoc.org/tags-module.html)):
@@ -228,6 +226,7 @@ var parse = require("jsdoc-parse")
228226
* [.private](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+private) : <code>boolean</code>
229227
* [.stats](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+stats) : <code>boolean</code>
230228
* [.html](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+html) : <code>boolean</code>
229+
* [.conf](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+conf) : <code>boolean</code>
231230
* [.sort-by](#module_jsdoc-parse--jsdocParse..ParseOptions+sort-by) : <code>array</code>
232231

233232
<a name="exp_module_jsdoc-parse--jsdocParse"></a>
@@ -253,6 +252,7 @@ All options for jsdoc-parse, including defaults
253252
* [.private](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+private) : <code>boolean</code>
254253
* [.stats](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+stats) : <code>boolean</code>
255254
* [.html](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+html) : <code>boolean</code>
255+
* [.conf](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+conf) : <code>boolean</code>
256256
* [.sort-by](#module_jsdoc-parse--jsdocParse..ParseOptions+sort-by) : <code>array</code>
257257

258258
<a name="module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+src"></a>
@@ -288,6 +288,12 @@ Enable experimental parsing of .html files.
288288

289289
**Kind**: instance property of <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code>
290290
**Default**: <code>false</code>
291+
<a name="module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+conf"></a>
292+
##### parseOptions.conf : <code>boolean</code>
293+
Path to a jsdoc configuration file, passed directly to `jsdoc -c`.
294+
295+
**Kind**: instance property of <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code>
296+
**Default**: <code></code>
291297
<a name="module_jsdoc-parse--jsdocParse..ParseOptions+sort-by"></a>
292298
##### parseOptions.sort-by : <code>array</code>
293299
Sort by one of more fields, e.g. `--sort-by kind category`. Pass the special value `none` to remove the default sort order.

‎es5/cli-options.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,6 @@ exports.definitions = [{
3939
exports.usage = {
4040
title: 'jsdoc-parse',
4141
description: 'Jsdoc-annotated source code in, JSON format documentation out.',
42-
forms: ['$ jsdoc-parse [-[bold]{PH}] [[bold]{--sort-by} [underline]{fields}] [[bold]{--src} [underline]{file} ...]', '$ jsdoc-parse [bold]{--help}', '$ jsdoc-parse [bold]{--stats}'],
42+
forms: ['$ jsdoc-parse [-[bold]{PH}] [[bold]{--sort-by} [underline]{fields}] [[bold]{--conf} [underline]{file}] [[bold]{--src} [underline]{file} ...]', '$ jsdoc-parse [bold]{--help}', '$ jsdoc-parse [bold]{--stats}'],
4343
optionNameStyles: 'bold'
4444
};

‎es5/jsdoc-parse.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ var ParseOptions = function ParseOptions() {
3232

3333
this.html = false;
3434

35+
this.conf = null;
36+
3537
this['sort-by'] = ['scope', 'category', 'kind', 'order'];
3638
};
3739

‎jsdoc2md/README.hbs‎

Lines changed: 22 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -7,23 +7,14 @@
77
# jsdoc-parse
88
Jsdoc-annotated source code in, JSON format documentation out.
99

10-
Essentially, the output is the raw JSON output of [jsdoc](https://github.com/jsdoc3/jsdoc) with a few extras:
10+
jsdoc-parse extends [jsdoc](https://github.com/jsdoc3/jsdoc) with a few features:
1111

1212
* Support for html input files (see `--html` option).
1313
* Support for new tags in the input javascript
1414
* `@category <string>`: Useful for grouping identifiers by category.
1515
* `@done`: Used to mark `@todo` items as complete.
1616
* `@typicalname`: If set on a class, namespace or module, child members will documented using this typical name as the parent name. Real-world typical name examples are `$` (the typical name for `jQuery` instances), `_` (underscore) etc.
1717
* `@chainable`: Set to mark a method as chainable (has a return value of `this`).
18-
* Some new fields:
19-
* `id`: a unique identifier (the jsdoc `longname` field is not guaranteed unique)
20-
* `isExported`: set to true on the identifier which is exported from a module.
21-
* `todoList`: A list.
22-
* `typicalname`
23-
* `category`
24-
* `order`: The sort position of the identifier in the source file. Useful for use in `--sort-by` expressions.
25-
* A separate constructor record. In jsdoc, the class and constructor information are contained within the same record. In jsdoc-parse, the constructor information is separated from the class into a record with kind `"constructor"`.
26-
2718

2819
## Synopsis
2920
### Simple example
@@ -177,29 +168,36 @@ $ jsdoc-parse example/doc.html --html
177168

178169
## Install and use
179170

180-
### Compatible Platforms
181-
Tested on Mac OSX, Linux, Windows 8.1 and Windows XP.
182-
183171
### As a command-line tool
184172
Useful for quick access to the data..
185173

186174
```
187175
$ npm install -g jsdoc-parse
188176
$ jsdoc-parse --help
189177

190-
jsdoc-parse
191-
Jsdoc-annotated source code in, JSON format documentation out.
178+
jsdoc-parse
192179

193-
Usage
194-
$ jsdoc-parse <files>
195-
$ cat <files> | jsdoc-parse
180+
Jsdoc-annotated source code in, JSON format documentation out.
196181

197-
--private Include identifiers marked @private in the output
198-
--stats Print a few stats about the doclets parsed
199-
--html Enable experimental parsing of .html files
200-
--src <array> A list of javascript source files or glob expressions
201-
-s, --sort-by <array> Sort by one of more fields, e.g. `--sort-by kind category`. Defaults to 'scope kind'.
202-
-h, --help
182+
Synopsis
183+
184+
$ jsdoc-parse [-PH] [--sort-by fields] [--conf file] [--src file ...]
185+
$ jsdoc-parse --help
186+
$ jsdoc-parse --stats
187+
188+
Options
189+
190+
-f, --src file ... A list of javascript source files (or glob expressions) to parse for
191+
documentation. If this option is not set jsdoc-parse will wait for source
192+
code on stdin (i.e. `cat *.js | jsdoc-parse [options]`).
193+
-P, --private Include identifiers marked @private in the output
194+
-H, --html Enable experimental parsing of .html files
195+
--conf file Path to a jsdoc configuration file, passed directly to `jsdoc -c`.
196+
-s, --sort-by property ... Sort by one of more properties, e.g. `--sort-by kind category`. Defaults to
197+
`[ "scope", "category", "kind", "order" ]`. Pass the special value `none` to
198+
remove the default sort order.
199+
--stats Print a few stats about the doclets parsed
200+
-h, --help Display this usage.
203201
```
204202

205203
***Usage form 2 warning***: When piping input into `jsdoc-parse` it will intepret the whole of what is piped in as a single file, so take care not to pipe in input containing multipe @modules as this is illegal in jsdoc (see [here](http://usejsdoc.org/tags-module.html)):

‎lib/cli-options.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ exports.usage = {
4545
title: 'jsdoc-parse',
4646
description: 'Jsdoc-annotated source code in, JSON format documentation out.',
4747
forms: [
48-
'$ jsdoc-parse [-[bold]{PH}] [[bold]{--sort-by} [underline]{fields}] [[bold]{--src} [underline]{file} ...]',
48+
'$ jsdoc-parse [-[bold]{PH}] [[bold]{--sort-by} [underline]{fields}] [[bold]{--conf} [underline]{file}] [[bold]{--src} [underline]{file} ...]',
4949
'$ jsdoc-parse [bold]{--help}',
5050
'$ jsdoc-parse [bold]{--stats}'
5151
],

‎lib/jsdoc-parse.js‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,13 @@ class ParseOptions {
6666
*/
6767
this.html = false
6868

69+
/**
70+
* Path to a jsdoc configuration file, passed directly to `jsdoc -c`.
71+
* @type {boolean}
72+
* @default
73+
*/
74+
this.conf = null
75+
6976
/**
7077
* Sort by one of more fields, e.g. `--sort-by kind category`. Pass the special value `none` to remove the default sort order.
7178
* @member module:jsdoc-parse~ParseOptions#sort-by

0 commit comments

Comments
 (0)