jsdoc-api v9.3.4
Upgraders, please check the release notes.
jsdoc-api
A programmatic interface for jsdoc3 with a few features:
- Asynchronous 'explain' and 'render documentation' methods (the two main jsdoc operations).
- Input (source code) can supplied as a string or set of file names and/or globs.
- Optional caching, dramatically speeding up future invocations with the same input.
Synopsis
To output an array of json objects, each representing a doclet, use .explain(). Pass in an array of file names and/or glob expressions. Use the cache: true
flag for a faster, more efficient invocation (cached output from a prior invocation will be returned if the input has not changed).
import jsdoc from 'jsdoc-api'
const data = await jsdoc.explain({ files: ['index.js', 'lib/*.js'], cache: true })
console.log(data)
Typical output (truncated):
[
{
comment: '/**\n' +
' * The [cache-point](https://github.com/75lb/cache-point) instance used when `cache: true` is specified on `.explain()`.\n' +
' * @type {external:cache-point}\n' +
' */',
meta: {
range: [ 491, 554 ],
filename: 'index.js',
lineno: 21,
columnno: 6,
path: '/Users/lloyd/Documents/jsdoc2md/jsdoc-api',
code: { id: 'astnode100000027', name: 'cache', type: 'NewExpression', value: '' }
},
description: 'The [cache-point](https://github.com/75lb/cache-point) instance used when `cache: true` is specified on `.explain()`.',
type: { names: [ 'external:cache-point' ] },
name: 'cache',
longname: 'module:jsdoc-api~cache',
kind: 'constant',
scope: 'inner',
memberof: 'module:jsdoc-api',
params: []
},
// etc
// etc
]
As an alternative to passing in file names/globs (above), you can pass in one or more source code strings.
import jsdoc from 'jsdoc-api'
const data = await jsdoc.explain({ source: '/** example doclet */ \n var example = true' })
console.log(data)
Output:
[
{
comment: '/** example doclet */',
meta: {
range: [ 28, 42 ],
filename: '934b1fbe2810.js',
lineno: 2,
columnno: 5,
path: '/var/folders/bt/jgn73jf50vsb5gj92dk00v3r0000gn/T/jsdoc-api-W854dk',
code: { id: 'astnode100000003', name: 'example', type: 'Literal', value: true }
},
description: 'example doclet',
name: 'example',
longname: 'example',
kind: 'member',
scope: 'global',
params: []
},
{ kind: 'package', longname: 'package:undefined', files: [ '/var/folders/bt/jgn73jf50vsb5gj92dk00v3r0000gn/T/jsdoc-api-W854dk/934b1fbe2810.js' ] }
]
Finally, use the render()
method to invocate jsdoc directly, generating your documentation.
import jsdoc from 'jsdoc-api'
await jsdoc.render({ files: ['index.js', 'lib/something.js'], destination: 'jsdoc-output' })
If you need to use a specific jsdoc
version or fork, specify its path via JSDOC_PATH
and jsdoc-api will use it instead of the default.
$ export JSDOC_PATH=./node_modules/.bin/jsdoc # An alternative jsdoc version you installed
$ node my-jsdoc-api-script.js # Run your jsdoc-api app as usual
See the API documentation for further details. See the example folder for code examples.
© 2015-24 Lloyd Brookes \75pound@gmail.com\.
Tested by test-runner. Documented by jsdoc-to-markdown.
8 months ago
10 months ago
9 months ago
9 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
12 months ago
11 months ago
10 months ago
10 months ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
5 years ago
6 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
8 years ago
8 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago