README.md

jsdoc-api

A programmatic interface for jsdoc3 with a few extra features.

• Provides sync, async (Promise) and streaming interfaces for the two main jsdoc operations ('explain' and 'render documentation').
• Supply source code via a string, a set of file names or a stream.
• Optional caching, dramatically boosting subsequent run performance on the same input.
• Supports .html input files documenting the contained javascript.

Example

> 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' ] } ]

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

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.createExplainStream([options]) ⇒ Duplex

Returns a duplex stream, into which you can pipe source code and receive explain output at the other end.

Kind: static method of jsdoc-api

Param	Type
[options]	JsdocOptions

Example

fs.createReadStream('source-code.js')
  .pipe(jsdoc.createExplainStream())
  .pipe(process.stdout)

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.clean() ⇒ Promise

Clean the cache.

Kind: static method of jsdoc-api

jsdoc~JsdocOptions

The jsdoc options, common for all operations.

Kind: inner class of jsdoc-api

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

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

options.html : boolean

Enable experimental parsing of .html files.

Kind: instance property of JsdocOptions

---

© 2015-16 Lloyd Brookes <[email protected]>. Documented by jsdoc-to-markdown.