A programmatic interface for jsdoc3 with a few extra features
Clone or download
Latest commit d41fa00 Feb 23, 2018

README.md

view on npm npm module downloads Build Status Coverage Status Dependency Status js-standard-style Join the chat at https://gitter.im/jsdoc2md/jsdoc2md

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.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

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 source 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-18 Lloyd Brookes <75pound@gmail.com>. Documented by jsdoc-to-markdown.