Skip to content

Commit 564303f

Browse files
75lb75lb
committed
docs
1 parent fd3bb2a commit 564303f

File tree

11 files changed

+297
-297
lines changed

11 files changed

+297
-297
lines changed

‎README.md

Lines changed: 68 additions & 186 deletions
Original file line numberDiff line numberDiff line change
@@ -9,211 +9,93 @@
99

1010
A programmatic interface for [jsdoc3](https://github.com/jsdoc3/jsdoc) with a few features:
1111

12-
- Sync and async (Promise) interfaces on the two main jsdoc operations ('explain' and 'render documentation').
12+
- Asynchronous 'explain' and 'render documentation' methods (the two main jsdoc operations).
1313
- Input (source code) can supplied as a string or set of file names/globs.
1414
- Optional caching, dramatically speeding up future invocations with the same input.
1515

1616
## Synopsis
1717

18+
To output an array of json objects, each representing a doclet, use `.explain()`. Pass in an array of file names and/or glob expressions. The `cache: true` flag tells jsdoc-api to return the same output on future invocations if the input has not changed.
19+
1820
```js
19-
> const jsdoc = require('jsdoc-api')
21+
import jsdoc from 'jsdoc-api'
2022

21-
> jsdoc.explainSync({ source: '/** example doclet */ \n var example = true' })
22-
[ { comment: '/** example doclet *∕',
23-
meta:
24-
{ range: [ 28, 42 ],
25-
filename: 'nkrf18zlymohia4i29a0zkyt84obt9.js',
26-
lineno: 2,
27-
path: '/var/folders/74/tqh7thm11tq72d7sjty9qvdh0000gn/T',
28-
code:
29-
{ id: 'astnode100000002',
30-
name: 'example',
31-
type: 'Literal',
32-
value: true } },
33-
description: 'example doclet',
34-
name: 'example',
35-
longname: 'example',
36-
kind: 'member',
37-
scope: 'global' },
38-
{ kind: 'package',
39-
longname: 'package:undefined',
40-
files: [ '/var/folders/74/tqh7thm11tq72d7sjty9qvdh0000gn/T/nkrf18zlymohia4i29a0zkyt84obt9.js' ] } ]
23+
const data = await jsdoc.explain({ files: ['index.js', 'lib/*.js'], cache: true })
24+
console.log(data)
4125
```
4226

43-
# API Reference
44-
45-
46-
* [jsdoc-api](#module_jsdoc-api)
47-
* _static_
48-
* [.explain([options])](#module_jsdoc-api.explain) ⇒ <code>Promise</code>
49-
* [.render([options])](#module_jsdoc-api.render)
50-
* _inner_
51-
* [~JsdocOptions](#module_jsdoc-api..JsdocOptions)
52-
* [.files](#module_jsdoc-api..JsdocOptions+files) : <code>string</code> \| <code>Array.&lt;string&gt;</code>
53-
* [.source](#module_jsdoc-api..JsdocOptions+source) : <code>string</code>
54-
* [.cache](#module_jsdoc-api..JsdocOptions+cache) : <code>boolean</code>
55-
* [.access](#module_jsdoc-api..JsdocOptions+access) : <code>string</code>
56-
* [.configure](#module_jsdoc-api..JsdocOptions+configure) : <code>string</code>
57-
* [.destination](#module_jsdoc-api..JsdocOptions+destination) : <code>string</code>
58-
* [.encoding](#module_jsdoc-api..JsdocOptions+encoding) : <code>string</code>
59-
* [.private](#module_jsdoc-api..JsdocOptions+private) : <code>boolean</code>
60-
* [.package](#module_jsdoc-api..JsdocOptions+package) : <code>string</code>
61-
* [.pedantic](#module_jsdoc-api..JsdocOptions+pedantic) : <code>boolean</code>
62-
* [.query](#module_jsdoc-api..JsdocOptions+query) : <code>string</code>
63-
* [.recurse](#module_jsdoc-api..JsdocOptions+recurse) : <code>boolean</code>
64-
* [.readme](#module_jsdoc-api..JsdocOptions+readme) : <code>string</code>
65-
* [.template](#module_jsdoc-api..JsdocOptions+template) : <code>string</code>
66-
* [.tutorials](#module_jsdoc-api..JsdocOptions+tutorials) : <code>string</code>
67-
* [~cache](#module_jsdoc-api..cache) : [<code>cache-point</code>](https://github.com/75lb/cache-point)
68-
69-
<a name="module_jsdoc-api.explain"></a>
70-
71-
### jsdoc.explain([options]) ⇒ <code>Promise</code>
72-
Returns a promise for the jsdoc explain output.
73-
74-
**Kind**: static method of [<code>jsdoc-api</code>](#module_jsdoc-api)
75-
**Fulfil**: <code>object[]</code> - jsdoc explain output
76-
77-
| Param | Type |
78-
| --- | --- |
79-
| [options] | [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions) |
80-
81-
<a name="module_jsdoc-api.render"></a>
82-
83-
### jsdoc.render([options])
84-
Render jsdoc documentation.
85-
86-
**Kind**: static method of [<code>jsdoc-api</code>](#module_jsdoc-api)
87-
**Prerequisite**: Requires node v0.12 or above
88-
89-
| Param | Type |
90-
| --- | --- |
91-
| [options] | [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions) |
92-
93-
**Example**
27+
Typical output (truncated):
28+
9429
```js
95-
await jsdoc.render({ files: 'lib/*', destination: 'api-docs' })
30+
[
31+
{
32+
comment: '/**\n' +
33+
' * The [cache-point](https://github.com/75lb/cache-point) instance used when `cache: true` is specified on `.explain()`.\n' +
34+
' * @type {external:cache-point}\n' +
35+
' */',
36+
meta: {
37+
range: [ 491, 554 ],
38+
filename: 'index.js',
39+
lineno: 21,
40+
columnno: 6,
41+
path: '/Users/lloyd/Documents/jsdoc2md/jsdoc-api',
42+
code: { id: 'astnode100000027', name: 'cache', type: 'NewExpression', value: '' }
43+
},
44+
description: 'The [cache-point](https://github.com/75lb/cache-point) instance used when `cache: true` is specified on `.explain()`.',
45+
type: { names: [ 'external:cache-point' ] },
46+
name: 'cache',
47+
longname: 'module:jsdoc-api~cache',
48+
kind: 'constant',
49+
scope: 'inner',
50+
memberof: 'module:jsdoc-api',
51+
params: []
52+
},
53+
// etc
54+
// etc
55+
]
9656
```
97-
<a name="module_jsdoc-api..JsdocOptions"></a>
98-
99-
### jsdoc-api~JsdocOptions
100-
The jsdoc options, common for all operations.
101-
102-
**Kind**: inner class of [<code>jsdoc-api</code>](#module_jsdoc-api)
103-
104-
* [~JsdocOptions](#module_jsdoc-api..JsdocOptions)
105-
* [.files](#module_jsdoc-api..JsdocOptions+files) : <code>string</code> \| <code>Array.&lt;string&gt;</code>
106-
* [.source](#module_jsdoc-api..JsdocOptions+source) : <code>string</code>
107-
* [.cache](#module_jsdoc-api..JsdocOptions+cache) : <code>boolean</code>
108-
* [.access](#module_jsdoc-api..JsdocOptions+access) : <code>string</code>
109-
* [.configure](#module_jsdoc-api..JsdocOptions+configure) : <code>string</code>
110-
* [.destination](#module_jsdoc-api..JsdocOptions+destination) : <code>string</code>
111-
* [.encoding](#module_jsdoc-api..JsdocOptions+encoding) : <code>string</code>
112-
* [.private](#module_jsdoc-api..JsdocOptions+private) : <code>boolean</code>
113-
* [.package](#module_jsdoc-api..JsdocOptions+package) : <code>string</code>
114-
* [.pedantic](#module_jsdoc-api..JsdocOptions+pedantic) : <code>boolean</code>
115-
* [.query](#module_jsdoc-api..JsdocOptions+query) : <code>string</code>
116-
* [.recurse](#module_jsdoc-api..JsdocOptions+recurse) : <code>boolean</code>
117-
* [.readme](#module_jsdoc-api..JsdocOptions+readme) : <code>string</code>
118-
* [.template](#module_jsdoc-api..JsdocOptions+template) : <code>string</code>
119-
* [.tutorials](#module_jsdoc-api..JsdocOptions+tutorials) : <code>string</code>
120-
121-
<a name="module_jsdoc-api..JsdocOptions+files"></a>
122-
123-
#### options.files : <code>string</code> \| <code>Array.&lt;string&gt;</code>
124-
One or more filenames to process. Either this or `source` must be supplied.
125-
126-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
127-
<a name="module_jsdoc-api..JsdocOptions+source"></a>
128-
129-
#### options.source : <code>string</code>
130-
A string containing source code to process. Either this or `files` must be supplied.
131-
132-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
133-
<a name="module_jsdoc-api..JsdocOptions+cache"></a>
134-
135-
#### options.cache : <code>boolean</code>
136-
Set to `true` to cache the output - future invocations with the same input will return immediately.
137-
138-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
139-
<a name="module_jsdoc-api..JsdocOptions+access"></a>
140-
141-
#### options.access : <code>string</code>
142-
Only display symbols with the given access: "public", "protected", "private" or "undefined", or "all" for all access levels. Default: all except "private".
143-
144-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
145-
<a name="module_jsdoc-api..JsdocOptions+configure"></a>
146-
147-
#### options.configure : <code>string</code>
148-
The path to the configuration file. Default: path/to/jsdoc/conf.json.
149-
150-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
151-
<a name="module_jsdoc-api..JsdocOptions+destination"></a>
152-
153-
#### options.destination : <code>string</code>
154-
The path to the output folder. Use "console" to dump data to the console. Default: ./out/.
155-
156-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
157-
<a name="module_jsdoc-api..JsdocOptions+encoding"></a>
15857

159-
#### options.encoding : <code>string</code>
160-
Assume this encoding when reading all source files. Default: utf8.
58+
As an alternative to passing in file names/globs (above), you can pass in a source code string.
16159

162-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
163-
<a name="module_jsdoc-api..JsdocOptions+private"></a>
164-
165-
#### options.private : <code>boolean</code>
166-
Display symbols marked with the @private tag. Equivalent to "--access all". Default: false.
167-
168-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
169-
<a name="module_jsdoc-api..JsdocOptions+package"></a>
170-
171-
#### options.package : <code>string</code>
172-
The path to the project's package file. Default: path/to/sourcefiles/package.json
173-
174-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
175-
<a name="module_jsdoc-api..JsdocOptions+pedantic"></a>
176-
177-
#### options.pedantic : <code>boolean</code>
178-
Treat errors as fatal errors, and treat warnings as errors. Default: false.
179-
180-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
181-
<a name="module_jsdoc-api..JsdocOptions+query"></a>
182-
183-
#### options.query : <code>string</code>
184-
A query string to parse and store in jsdoc.env.opts.query. Example: foo=bar&baz=true.
185-
186-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
187-
<a name="module_jsdoc-api..JsdocOptions+recurse"></a>
188-
189-
#### options.recurse : <code>boolean</code>
190-
Recurse into subdirectories when scanning for source files and tutorials.
191-
192-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
193-
<a name="module_jsdoc-api..JsdocOptions+readme"></a>
194-
195-
#### options.readme : <code>string</code>
196-
The path to the project's README file. Default: path/to/sourcefiles/README.md.
197-
198-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
199-
<a name="module_jsdoc-api..JsdocOptions+template"></a>
60+
```js
61+
import jsdoc from 'jsdoc-api'
20062

201-
#### options.template : <code>string</code>
202-
The path to the template to use. Default: path/to/jsdoc/templates/default.
63+
const data = await jsdoc.explain({ source: '/** example doclet */ \n var example = true' })
64+
console.log(data)
65+
```
20366

204-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
205-
<a name="module_jsdoc-api..JsdocOptions+tutorials"></a>
67+
Output:
20668

207-
#### options.tutorials : <code>string</code>
208-
Directory in which JSDoc should search for tutorials.
69+
```js
70+
[
71+
{
72+
comment: '/** example doclet */',
73+
meta: {
74+
range: [ 28, 42 ],
75+
filename: '934b1fbe2810.js',
76+
lineno: 2,
77+
columnno: 5,
78+
path: '/var/folders/bt/jgn73jf50vsb5gj92dk00v3r0000gn/T/jsdoc-api-W854dk',
79+
code: { id: 'astnode100000003', name: 'example', type: 'Literal', value: true }
80+
},
81+
description: 'example doclet',
82+
name: 'example',
83+
longname: 'example',
84+
kind: 'member',
85+
scope: 'global',
86+
params: []
87+
},
88+
{ kind: 'package', longname: 'package:undefined', files: [ '/var/folders/bt/jgn73jf50vsb5gj92dk00v3r0000gn/T/jsdoc-api-W854dk/934b1fbe2810.js' ] }
89+
]
90+
```
20991

210-
**Kind**: instance property of [<code>JsdocOptions</code>](#module_jsdoc-api..JsdocOptions)
211-
<a name="module_jsdoc-api..cache"></a>
92+
Finally, use the `render()` method to invocate jsdoc directly, generating your documentation.
21293

213-
### jsdoc-api~cache : [<code>cache-point</code>](https://github.com/75lb/cache-point)
214-
The [cache-point](https://github.com/75lb/cache-point) instance used when `cache: true` is specified on `.explain()` or `.explainSync()`.
94+
```js
95+
import jsdoc from 'jsdoc-api'
21596

216-
**Kind**: inner constant of [<code>jsdoc-api</code>](#module_jsdoc-api)
97+
await jsdoc.render({ files: ['index.js', 'lib/*.js'], destination: 'jsdoc-output' })
98+
```
21799

218100
* * *
219101

0 commit comments

Comments
 (0)