Skip to content

Commit 4fdc0e5

Browse files
75lb75lb
committed
readme
1 parent b9b73cf commit 4fdc0e5

2 files changed

Lines changed: 55 additions & 268 deletions

File tree

‎README.md‎

Lines changed: 30 additions & 268 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
[![Join the chat at https://gitter.im/jsdoc2md/jsdoc2md](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jsdoc2md/jsdoc2md?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
77

88
# jsdoc-parse
9-
Jsdoc-annotated source code in, JSON format documentation out.
9+
Jsdoc explain out in, jsdoc2md template data out.
1010

1111
jsdoc-parse extends [jsdoc](https://github.com/jsdoc3/jsdoc) with a few features:
1212

@@ -17,288 +17,50 @@ jsdoc-parse extends [jsdoc](https://github.com/jsdoc3/jsdoc) with a few features
1717
* `@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.
1818
* `@chainable`: Set to mark a method as chainable (has a return value of `this`).
1919

20-
## Synopsis
21-
### Simple example
22-
```
23-
$ echo "/** a wonderful global */ var majestic = true;" | jsdoc-parse
24-
[
25-
{
26-
"id": "majestic",
27-
"longname": "majestic",
28-
"name": "majestic",
29-
"scope": "global",
30-
"kind": "member",
31-
"description": "a wonderful global",
32-
"order": 0
33-
}
34-
]
35-
```
36-
37-
### Longer example
38-
This input javascript:
39-
```js
40-
/**
41-
Pump an idiot full of volts. Returns a promise they will slump.
42-
@deprecated
43-
@param {object | array} - the victim(s) to fry
44-
@param [crazyHair=true] {boolean} - optional spikey hair effect
45-
@return {external:Promise}
46-
@resolve {Slump}
47-
*/
48-
function taze(victim, crazyHair){}
49-
```
50-
51-
returns this JSON:
52-
```json
53-
$ jsdoc-parse example/function.js
54-
[
55-
{
56-
"id": "taze",
57-
"longname": "taze",
58-
"name": "taze",
59-
"scope": "global",
60-
"kind": "function",
61-
"description": "Pump an idiot full of volts. Returns a promise they will slump.",
62-
"params": [
63-
{
64-
"type": {
65-
"names": [
66-
"object",
67-
"array"
68-
]
69-
},
70-
"description": "the victim(s) to fry",
71-
"name": "victim"
72-
},
73-
{
74-
"type": {
75-
"names": [
76-
"boolean"
77-
]
78-
},
79-
"optional": true,
80-
"defaultvalue": true,
81-
"description": "optional spikey hair effect",
82-
"name": "crazyHair"
83-
}
84-
],
85-
"returns": [
86-
{
87-
"type": {
88-
"names": [
89-
"external:Promise"
90-
]
91-
}
92-
}
93-
],
94-
"deprecated": true,
95-
"customTags": [
96-
{
97-
"tag": "resolve",
98-
"value": "{Slump}"
99-
}
100-
],
101-
"order": 0
102-
}
103-
]
104-
```
105-
106-
### HTML input example
107-
This input HTML:
108-
```html
109-
<!DOCTYPE html>
110-
<html>
111-
<head>
112-
<script>
113-
/**
114-
something in the head
115-
@type {number}
116-
*/
117-
var headGlobal = 1;
118-
</script>
119-
</head>
120-
<body class="main">
121-
<script>
122-
/**
123-
body global
124-
@type {string}
125-
@default
126-
*/
127-
var bodyGlobal = "one";
128-
129-
</script>
130-
</body>
131-
</html>
132-
```
133-
134-
produces this JSON output:
135-
```json
136-
$ jsdoc-parse example/doc.html --html
137-
[
138-
{
139-
"id": "headGlobal",
140-
"longname": "headGlobal",
141-
"name": "headGlobal",
142-
"scope": "global",
143-
"kind": "member",
144-
"description": "something in the head",
145-
"type": {
146-
"names": [
147-
"number"
148-
]
149-
},
150-
"order": 0
151-
},
152-
{
153-
"id": "bodyGlobal",
154-
"longname": "bodyGlobal",
155-
"name": "bodyGlobal",
156-
"scope": "global",
157-
"kind": "member",
158-
"description": "body global",
159-
"type": {
160-
"names": [
161-
"string"
162-
]
163-
},
164-
"defaultvalue": "one",
165-
"order": 1
166-
}
167-
]
168-
```
169-
170-
## Install and use
171-
172-
### As a command-line tool
173-
Useful for quick access to the data..
174-
175-
```
176-
jsdoc-parse
177-
178-
Jsdoc-annotated source code in, JSON format documentation out.
179-
180-
Synopsis
181-
182-
$ jsdoc-parse [-PH] [--sort-by fields] [--conf file] [--src file ...]
183-
$ jsdoc-parse --help
184-
$ jsdoc-parse --stats
185-
186-
Options
187-
188-
-f, --src file ... A list of javascript source files (or glob expressions) to parse for
189-
documentation. If this option is not set jsdoc-parse will wait for source
190-
code on stdin (i.e. `cat *.js | jsdoc-parse [options]`).
191-
-P, --private Include identifiers marked @private in the output
192-
-H, --html Enable experimental parsing of .html files
193-
--conf file Path to a jsdoc configuration file, passed directly to `jsdoc -c`.
194-
-s, --sort-by property ... Sort by one of more properties, e.g. `--sort-by kind category`. Defaults to
195-
`[ "scope", "category", "kind", "order" ]`. Pass the special value `none` to
196-
remove the default sort order.
197-
--stats Print a few stats about the doclets parsed
198-
-h, --help Display this usage.
199-
```
200-
201-
***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)):
202-
203-
> The @module tag marks the current file as being its own module. All symbols in the file are assumed to be members of the module unless documented otherwise.
204-
205-
### As a library
206-
For use within your node.js app.
207-
208-
```sh
209-
$ npm install jsdoc-parse --save
210-
```
211-
21220
## API Reference
213-
Exports a single function to parse jsdoc data.
21421

215-
**Example**
22+
<a name="module_jsdoc-parse"></a>
23+
24+
**Example**
21625
```js
217-
var parse = require("jsdoc-parse")
26+
var jsdocParse = require('jsdoc-parse')
21827
```
21928

220-
* [jsdoc-parse](#module_jsdoc-parse)
221-
* [jsdocParse([options])](#exp_module_jsdoc-parse--jsdocParse) ⇒ <code>[TransformStream](http://nodejs.org/api/stream.html#stream_class_stream_transform)</code> ⏏
222-
* [~ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)
223-
* [.src](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+src) : <code>string</code> &#124; <code>Array.&lt;string&gt;</code>
224-
* [.private](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+private) : <code>boolean</code>
225-
* [.stats](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+stats) : <code>boolean</code>
226-
* [.html](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+html) : <code>boolean</code>
227-
* [.conf](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+conf) : <code>boolean</code>
228-
* [.sort-by](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+sort-by) : <code>array</code>
29+
* jsdoc-parse
30+
* [~parse(jsdocExplainOutput, [options])](#module_jsdoc-parse..parse)
31+
* [~applyOptions(data, options)](#module_jsdoc-parse..applyOptions) ⇒ `string`
32+
* [~getStats(data)](#module_jsdoc-parse..getStats) ⇒ `object`
22933

230-
<a name="exp_module_jsdoc-parse--jsdocParse"></a>
231-
### jsdocParse([options]) ⇒ <code>[TransformStream](http://nodejs.org/api/stream.html#stream_class_stream_transform)</code> ⏏
232-
Documented javascript source in, documentation JSON out.
23334

234-
**Kind**: Exported function
35+
<a name="module_jsdoc-parse..parse"></a>
36+
### jsdoc-parse~parse(jsdocExplainOutput, [options])
37+
**Kind**: inner method of module:jsdoc-parse
23538
**Params**
236-
- [options] <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code> - parse options
23739

238-
**Example**
239-
```js
240-
parse({ src:"lib/jsdoc-parse.js" }).pipe(process.stdout)
241-
```
242-
<a name="module_jsdoc-parse--jsdocParse..ParseOptions"></a>
243-
#### jsdocParse~ParseOptions
244-
All options for jsdoc-parse, including defaults
40+
- jsdocExplainOutput Array.<object> - jsdoc output
41+
- [options] object
42+
- [.private] boolean - Include identifier documentation marked as `@private` in the output
43+
- [.html] boolean - Enable experimental parsing of .html files.
44+
- [.sort-by] Array.<string> <code> = [ 'scope', 'category', 'kind', 'order' ]</code> - Sort by one of more fields, e.g. `--sort-by kind category`. Pass the special value `none` to remove the default sort order.
24545

246-
**Kind**: inner class of <code>[jsdocParse](#exp_module_jsdoc-parse--jsdocParse)</code>
247-
248-
* [~ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)
249-
* [.src](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+src) : <code>string</code> &#124; <code>Array.&lt;string&gt;</code>
250-
* [.private](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+private) : <code>boolean</code>
251-
* [.stats](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+stats) : <code>boolean</code>
252-
* [.html](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+html) : <code>boolean</code>
253-
* [.conf](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+conf) : <code>boolean</code>
254-
* [.sort-by](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+sort-by) : <code>array</code>
255-
256-
<a name="module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+src"></a>
257-
##### parseOptions.src : <code>string</code> &#124; <code>Array.&lt;string&gt;</code>
258-
A list of javascript source files (or glob expressions) to parse for documentation. If this option is not set jsdoc-parse will wait for source code on stdin (i.e. `cat *.js | jsdoc-parse <options>`).
259-
260-
**Kind**: instance property of <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code>
261-
**Example**
262-
```js
263-
var parse = require("jsdoc-parse")
264-
var fs = require("fs")
265-
266-
// either supply one or more file names
267-
parse({ src: "example.js" }).pipe(process.stdout)
268-
269-
// or pipe in source code
270-
fs.createReadStream("example.js").parse().pipe(process.stdout)
271-
```
272-
<a name="module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+private"></a>
273-
##### parseOptions.private : <code>boolean</code>
274-
Include identifier documentation marked as `@private` in the output
46+
<a name="module_jsdoc-parse..applyOptions"></a>
47+
### jsdoc-parse~applyOptions(data, options) ⇒ `string`
48+
**Kind**: inner method of module:jsdoc-parse
49+
**Params**
27550

276-
**Kind**: instance property of <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code>
277-
**Default**: <code>false</code>
278-
<a name="module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+stats"></a>
279-
##### parseOptions.stats : <code>boolean</code>
280-
Print a few stats about the doclets parsed
51+
- data string - input json string
52+
- options object - jsdoc-parse options
28153

282-
**Kind**: instance property of <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code>
283-
<a name="module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+html"></a>
284-
##### parseOptions.html : <code>boolean</code>
285-
Enable experimental parsing of .html files.
54+
<a name="module_jsdoc-parse..getStats"></a>
55+
### jsdoc-parse~getStats(data) ⇒ `object`
56+
return some stats about the parsed data
28657

287-
**Kind**: instance property of <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code>
288-
**Default**: <code>false</code>
289-
<a name="module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+conf"></a>
290-
##### parseOptions.conf : <code>boolean</code>
291-
Path to a jsdoc configuration file, passed directly to `jsdoc -c`.
58+
**Kind**: inner method of module:jsdoc-parse
59+
**Params**
29260

293-
**Kind**: instance property of <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code>
294-
**Default**: <code></code>
295-
<a name="module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+sort-by"></a>
296-
##### parseOptions.sort-by : <code>array</code>
297-
Sort by one of more fields, e.g. `--sort-by kind category`. Pass the special value `none` to remove the default sort order.
61+
- data object - jsdoc-parse data
29862

299-
**Kind**: instance property of <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code>
300-
**Default**: <code>[&quot;scope&quot;,&quot;category&quot;,&quot;kind&quot;,&quot;order&quot;]</code>
30163

30264
* * *
30365

304-
&copy; 2015 Lloyd Brookes \<75pound@gmail.com\>. Documented by [jsdoc-to-markdown](https://github.com/75lb/jsdoc-to-markdown).
66+
&copy; 2015 Lloyd Brookes <75pound@gmail.com>. Documented by [jsdoc-to-markdown](https://github.com/75lb/jsdoc-to-markdown).

‎jsdoc2md/README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
[![view on npm](http://img.shields.io/npm/v/jsdoc-parse.svg)](https://www.npmjs.org/package/jsdoc-parse)
2+
[![npm module downloads](http://img.shields.io/npm/dt/jsdoc-parse.svg)](https://www.npmjs.org/package/jsdoc-parse)
3+
[![Build Status](https://travis-ci.org/jsdoc2md/jsdoc-parse.svg?branch=master)](https://travis-ci.org/jsdoc2md/jsdoc-parse)
4+
[![Dependency Status](https://david-dm.org/jsdoc2md/jsdoc-parse.svg)](https://david-dm.org/jsdoc2md/jsdoc-parse)
5+
[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://github.com/feross/standard)
6+
[![Join the chat at https://gitter.im/jsdoc2md/jsdoc2md](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jsdoc2md/jsdoc2md?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
7+
8+
# jsdoc-parse
9+
Jsdoc explain out in, jsdoc2md template data out.
10+
11+
jsdoc-parse extends [jsdoc](https://github.com/jsdoc3/jsdoc) with a few features:
12+
13+
* Support for html input files (see `--html` option).
14+
* Support for new tags in the input javascript
15+
* `@category <string>`: Useful for grouping identifiers by category.
16+
* `@done`: Used to mark `@todo` items as complete.
17+
* `@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.
18+
* `@chainable`: Set to mark a method as chainable (has a return value of `this`).
19+
20+
## API Reference
21+
${docs.renderAll()}
22+
23+
* * *
24+
25+
&copy; 2015 Lloyd Brookes \<75pound@gmail.com\>. Documented by [jsdoc-to-markdown](https://github.com/75lb/jsdoc-to-markdown).

0 commit comments

Comments
 (0)