Skip to content

Commit 97e7c76

Browse files
75lb75lb
committed
Merge branch 'next'
2 parents 712c65a + 04c63da commit 97e7c76

24 files changed

+741
-1439
lines changed

‎.travis.yml‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
language: node_js
22
node_js:
3-
- '5'
4-
- '4'
5-
- '0.12'
6-
- '0.10'
7-
- 'iojs'
3+
- 6
4+
- 5
5+
- 4
6+
- iojs
7+
- 0.12
8+
- '0.10'

‎LICENSE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
The MIT License (MIT)
22

3-
Copyright (c) 2015 Lloyd Brookes <[email protected]>
3+
Copyright (c) 2014-16 Lloyd Brookes <[email protected]>
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md‎

Lines changed: 10 additions & 270 deletions
Original file line numberDiff line numberDiff line change
@@ -8,299 +8,39 @@
88
***[Try the jsdoc2md v2 pre-release](https://github.com/jsdoc2md/jsdoc-to-markdown/releases)***
99

1010
# jsdoc-parse
11-
Jsdoc-annotated source code in, JSON format documentation out.
11+
Transforms [jsdoc](https://github.com/jsdoc3/jsdoc) data into something more suitable for use as template input. Also adds a few tags to the default set:
1212

13-
jsdoc-parse extends [jsdoc](https://github.com/jsdoc3/jsdoc) with a few features:
14-
15-
* Support for html input files (see `--html` option).
1613
* Support for new tags in the input javascript
1714
* `@category <string>`: Useful for grouping identifiers by category.
1815
* `@done`: Used to mark `@todo` items as complete.
1916
* `@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.
2017
* `@chainable`: Set to mark a method as chainable (has a return value of `this`).
2118

22-
## Synopsis
23-
### Simple example
24-
```
25-
$ echo "/** a wonderful global */ var majestic = true;" | jsdoc-parse
26-
[
27-
{
28-
"id": "majestic",
29-
"longname": "majestic",
30-
"name": "majestic",
31-
"scope": "global",
32-
"kind": "member",
33-
"description": "a wonderful global",
34-
"order": 0
35-
}
36-
]
37-
```
19+
## Command-line usage
3820

39-
### Longer example
40-
This input javascript:
41-
```js
42-
/**
43-
Pump an idiot full of volts. Returns a promise they will slump.
44-
@deprecated
45-
@param {object | array} - the victim(s) to fry
46-
@param [crazyHair=true] {boolean} - optional spikey hair effect
47-
@return {external:Promise}
48-
@resolve {Slump}
49-
*/
50-
function taze(victim, crazyHair){}
51-
```
21+
This module is built into [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown/), you can see the output using this command:
5222

53-
returns this JSON:
54-
```json
55-
$ jsdoc-parse example/function.js
56-
[
57-
{
58-
"id": "taze",
59-
"longname": "taze",
60-
"name": "taze",
61-
"scope": "global",
62-
"kind": "function",
63-
"description": "Pump an idiot full of volts. Returns a promise they will slump.",
64-
"params": [
65-
{
66-
"type": {
67-
"names": [
68-
"object",
69-
"array"
70-
]
71-
},
72-
"description": "the victim(s) to fry",
73-
"name": "victim"
74-
},
75-
{
76-
"type": {
77-
"names": [
78-
"boolean"
79-
]
80-
},
81-
"optional": true,
82-
"defaultvalue": true,
83-
"description": "optional spikey hair effect",
84-
"name": "crazyHair"
85-
}
86-
],
87-
"returns": [
88-
{
89-
"type": {
90-
"names": [
91-
"external:Promise"
92-
]
93-
}
94-
}
95-
],
96-
"deprecated": true,
97-
"customTags": [
98-
{
99-
"tag": "resolve",
100-
"value": "{Slump}"
101-
}
102-
],
103-
"order": 0
104-
}
105-
]
10623
```
107-
108-
### HTML input example
109-
This input HTML:
110-
```html
111-
<!DOCTYPE html>
112-
<html>
113-
<head>
114-
<script>
115-
/**
116-
something in the head
117-
@type {number}
118-
*/
119-
var headGlobal = 1;
120-
</script>
121-
</head>
122-
<body class="main">
123-
<script>
124-
/**
125-
body global
126-
@type {string}
127-
@default
128-
*/
129-
var bodyGlobal = "one";
130-
131-
</script>
132-
</body>
133-
</html>
134-
```
135-
136-
produces this JSON output:
137-
```json
138-
$ jsdoc-parse example/doc.html --html
139-
[
140-
{
141-
"id": "headGlobal",
142-
"longname": "headGlobal",
143-
"name": "headGlobal",
144-
"scope": "global",
145-
"kind": "member",
146-
"description": "something in the head",
147-
"type": {
148-
"names": [
149-
"number"
150-
]
151-
},
152-
"order": 0
153-
},
154-
{
155-
"id": "bodyGlobal",
156-
"longname": "bodyGlobal",
157-
"name": "bodyGlobal",
158-
"scope": "global",
159-
"kind": "member",
160-
"description": "body global",
161-
"type": {
162-
"names": [
163-
"string"
164-
]
165-
},
166-
"defaultvalue": "one",
167-
"order": 1
168-
}
169-
]
170-
```
171-
172-
## Install and use
173-
174-
### As a command-line tool
175-
Useful for quick access to the data..
176-
177-
```
178-
jsdoc-parse
179-
180-
Jsdoc-annotated source code in, JSON format documentation out.
181-
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.
201-
```
202-
203-
***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)):
204-
205-
> 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.
206-
207-
### As a library
208-
For use within your node.js app.
209-
210-
```sh
211-
$ npm install jsdoc-parse --save
24+
$ jsdoc2md --json <files>
21225
```
21326

21427
## API Reference
215-
Exports a single function to parse jsdoc data.
28+
<a name="module_jsdoc-parse"></a>
21629

30+
## jsdoc-parse
21731
**Example**
21832
```js
219-
var parse = require("jsdoc-parse")
33+
const jsdocParse = require('jsdoc-parse')
22034
```
221-
222-
* [jsdoc-parse](#module_jsdoc-parse)
223-
* [jsdocParse([options])](#exp_module_jsdoc-parse--jsdocParse) ⇒ <code>[TransformStream](http://nodejs.org/api/stream.html#stream_class_stream_transform)</code> ⏏
224-
* [~ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)
225-
* [.src](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+src) : <code>string</code> &#124; <code>Array.&lt;string&gt;</code>
226-
* [.private](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+private) : <code>boolean</code>
227-
* [.stats](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+stats) : <code>boolean</code>
228-
* [.html](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+html) : <code>boolean</code>
229-
* [.conf](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+conf) : <code>boolean</code>
230-
* [.sort-by](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+sort-by) : <code>array</code>
231-
23235
<a name="exp_module_jsdoc-parse--jsdocParse"></a>
233-
### jsdocParse([options]) ⇒ <code>[TransformStream](http://nodejs.org/api/stream.html#stream_class_stream_transform)</code> ⏏
234-
Documented javascript source in, documentation JSON out.
23536

37+
### jsdocParse(jsdocData) ⇒ <code>Array.&lt;object&gt;</code> ⏏
23638
**Kind**: Exported function
23739
**Params**
238-
- [options] <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code> - parse options
239-
240-
**Example**
241-
```js
242-
parse({ src:"lib/jsdoc-parse.js" }).pipe(process.stdout)
243-
```
244-
<a name="module_jsdoc-parse--jsdocParse..ParseOptions"></a>
245-
#### jsdocParse~ParseOptions
246-
All options for jsdoc-parse, including defaults
247-
248-
**Kind**: inner class of <code>[jsdocParse](#exp_module_jsdoc-parse--jsdocParse)</code>
249-
250-
* [~ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)
251-
* [.src](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+src) : <code>string</code> &#124; <code>Array.&lt;string&gt;</code>
252-
* [.private](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+private) : <code>boolean</code>
253-
* [.stats](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+stats) : <code>boolean</code>
254-
* [.html](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+html) : <code>boolean</code>
255-
* [.conf](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+conf) : <code>boolean</code>
256-
* [.sort-by](#module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+sort-by) : <code>array</code>
257-
258-
<a name="module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+src"></a>
259-
##### parseOptions.src : <code>string</code> &#124; <code>Array.&lt;string&gt;</code>
260-
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>`).
261-
262-
**Kind**: instance property of <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code>
263-
**Example**
264-
```js
265-
var parse = require("jsdoc-parse")
266-
var fs = require("fs")
267-
268-
// either supply one or more file names
269-
parse({ src: "example.js" }).pipe(process.stdout)
270-
271-
// or pipe in source code
272-
fs.createReadStream("example.js").pipe(parse()).pipe(process.stdout)
273-
```
274-
<a name="module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+private"></a>
275-
##### parseOptions.private : <code>boolean</code>
276-
Include identifier documentation marked as `@private` in the output
277-
278-
**Kind**: instance property of <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code>
279-
**Default**: <code>false</code>
280-
<a name="module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+stats"></a>
281-
##### parseOptions.stats : <code>boolean</code>
282-
Print a few stats about the doclets parsed
283-
284-
**Kind**: instance property of <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code>
285-
<a name="module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+html"></a>
286-
##### parseOptions.html : <code>boolean</code>
287-
Enable experimental parsing of .html files.
288-
289-
**Kind**: instance property of <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code>
290-
**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`.
29440

295-
**Kind**: instance property of <code>[ParseOptions](#module_jsdoc-parse--jsdocParse..ParseOptions)</code>
296-
**Default**: <code></code>
297-
<a name="module_jsdoc-parse--jsdocParse..ParseOptions.ParseOptions+sort-by"></a>
298-
##### parseOptions.sort-by : <code>array</code>
299-
Sort by one of more fields, e.g. `--sort-by kind category`. Pass the special value `none` to remove the default sort order.
41+
- jsdocData <code>Array.&lt;object&gt;</code> - jsdoc output
30042

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

30444
* * *
30545

306-
&copy; 2015 Lloyd Brookes \<[email protected]\>. Documented by [jsdoc-to-markdown](https://github.com/75lb/jsdoc-to-markdown).
46+
&copy; 2014-16 Lloyd Brookes \<[email protected]\>. Documented by [jsdoc-to-markdown](https://github.com/75lb/jsdoc-to-markdown).

‎bin/cli.js‎

Lines changed: 0 additions & 30 deletions
This file was deleted.

0 commit comments

Comments
 (0)