jsdoc-api

A programmatic interface for jsdoc3 with a few features:

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

Synopsis

> const jsdoc = require('jsdoc-api')

> jsdoc.explainSync({ source: '/** example doclet */ \n var example = true' })
[ { comment: '/** example doclet *∕',
   meta:
    { range: [ 28, 42 ],
      filename: 'nkrf18zlymohia4i29a0zkyt84obt9.js',
      lineno: 2,
      path: '/var/folders/74/tqh7thm11tq72d7sjty9qvdh0000gn/T',
      code:
       { id: 'astnode100000002',
         name: 'example',
         type: 'Literal',
         value: true } },
   description: 'example doclet',
   name: 'example',
   longname: 'example',
   kind: 'member',
   scope: 'global' },
 { kind: 'package',
   longname: 'package:undefined',
   files: [ '/var/folders/74/tqh7thm11tq72d7sjty9qvdh0000gn/T/nkrf18zlymohia4i29a0zkyt84obt9.js' ] } ]

API Reference

• jsdoc-api
  • static
    • .cache : cache-point
    • .explainSync([options]) ⇒ Array.<object>
    • .explain([options]) ⇒ Promise
    • .renderSync([options])
  • inner
    • ~JsdocOptions
      • .files : string | Array.<string>
      • .source : string
      • .cache : boolean
      • .access : string
      • .configure : string
      • .destination : string
      • .encoding : string
      • .private : boolean
      • .package : string
      • .pedantic : boolean
      • .query : string
      • .recurse : boolean
      • .readme : string
      • .template : string
      • .tutorials : string

jsdoc.cache : cache-point

The cache-point instance used when cache: true is specified on .explain() or .explainSync().

Kind: static property of jsdoc-api

jsdoc.explainSync([options]) ⇒ Array.<object>

Returns jsdoc explain output.

Kind: static method of jsdoc-api
Prerequisite: Requires node v0.12 or above

| Param | Type | | --- | --- | | [options] | JsdocOptions |

jsdoc.explain([options]) ⇒ Promise

Returns a promise for the jsdoc explain output.

Kind: static method of jsdoc-api
Fulfil: object[] - jsdoc explain output

| Param | Type | | --- | --- | | [options] | JsdocOptions |

jsdoc.renderSync([options])

Render jsdoc documentation.

Kind: static method of jsdoc-api
Prerequisite: Requires node v0.12 or above

| Param | Type | | --- | --- | | [options] | JsdocOptions |

Example

jsdoc.renderSync({ files: 'lib/*', destination: 'api-docs' })

jsdoc-api~JsdocOptions

The jsdoc options, common for all operations.

Kind: inner class of jsdoc-api

• ~JsdocOptions
  • .files : string | Array.<string>
  • .source : string
  • .cache : boolean
  • .access : string
  • .configure : string
  • .destination : string
  • .encoding : string
  • .private : boolean
  • .package : string
  • .pedantic : boolean
  • .query : string
  • .recurse : boolean
  • .readme : string
  • .template : string
  • .tutorials : string

options.files : string | Array.<string>

One or more filenames to process. Either this or source must be supplied.

Kind: instance property of JsdocOptions

options.source : string

A string containing source code to process. Either this or files must be supplied.

Kind: instance property of JsdocOptions

options.cache : boolean

Set to true to cache the output - future invocations with the same input will return immediately.

Kind: instance property of JsdocOptions

options.access : string

Only display symbols with the given access: "public", "protected", "private" or "undefined", or "all" for all access levels. Default: all except "private".

Kind: instance property of JsdocOptions

options.configure : string

The path to the configuration file. Default: path/to/jsdoc/conf.json.

Kind: instance property of JsdocOptions

options.destination : string

The path to the output folder. Use "console" to dump data to the console. Default: ./out/.

Kind: instance property of JsdocOptions

options.encoding : string

Assume this encoding when reading all source files. Default: utf8.

Kind: instance property of JsdocOptions

options.private : boolean

Display symbols marked with the @private tag. Equivalent to "--access all". Default: false.

Kind: instance property of JsdocOptions

options.package : string

The path to the project's package file. Default: path/to/sourcefiles/package.json

Kind: instance property of JsdocOptions

options.pedantic : boolean

Treat errors as fatal errors, and treat warnings as errors. Default: false.

Kind: instance property of JsdocOptions

options.query : string

A query string to parse and store in jsdoc.env.opts.query. Example: foo=bar&baz=true.

Kind: instance property of JsdocOptions

options.recurse : boolean

Recurse into subdirectories when scanning for source files and tutorials.

Kind: instance property of JsdocOptions

options.readme : string

The path to the project's README file. Default: path/to/sourcefiles/README.md.

Kind: instance property of JsdocOptions

options.template : string

The path to the template to use. Default: path/to/jsdoc/templates/default.

Kind: instance property of JsdocOptions

options.tutorials : string

Directory in which JSDoc should search for tutorials.

Kind: instance property of JsdocOptions

© 2015-22 Lloyd Brookes <[email protected]>.

Tested by test-runner. Documented by jsdoc-to-markdown.