jsdoc-api

What is jsdoc-api?

The jsdoc-api npm package provides a programmatic interface to JSDoc, allowing you to generate documentation from JavaScript source code comments. It can be used to parse JSDoc comments and generate JSON output, making it easier to integrate JSDoc functionality into build processes or other tools.

What are jsdoc-api's main functionalities?

Generate Documentation

This feature allows you to generate documentation from JavaScript files. The `renderSync` method processes the specified files and generates the documentation.

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

jsdoc.renderSync({
  files: 'path/to/your/file.js'
});

Parse JSDoc Comments

This feature allows you to parse JSDoc comments from a source string. The `explainSync` method returns a JSON representation of the parsed comments.

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

const docs = jsdoc.explainSync({
  source: '/**
   * A description of the function.
   * @param {string} name - The name of the person.
   * @returns {string} A greeting message.
   */
  function greet(name) {
    return `Hello, ${name}!`;
  }'
});

console.log(docs);

Configure JSDoc Options

This feature allows you to use a configuration file to customize the JSDoc generation process. The `configure` option specifies the path to a JSDoc configuration file.

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

const docs = jsdoc.explainSync({
  files: 'path/to/your/file.js',
  configure: 'path/to/jsdoc.conf.json'
});

console.log(docs);

Other packages similar to jsdoc-api

documentation

The `documentation` package is another tool for generating documentation from JavaScript comments. It offers a command-line interface and programmatic API, similar to jsdoc-api. It supports ES6+ syntax and can output documentation in various formats, including HTML and Markdown.

esdoc

The `esdoc` package is designed specifically for ES6+ JavaScript. It provides a comprehensive documentation generation tool with support for various plugins and themes. Compared to jsdoc-api, esdoc offers more modern syntax support and additional customization options.

typedoc

The `typedoc` package is a documentation generator for TypeScript projects. It generates documentation based on TypeScript type annotations and comments. While jsdoc-api focuses on JavaScript, typedoc is tailored for TypeScript, providing better integration with TypeScript's type system.

README

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])
  • 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~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 <[e-mail]>. Documented by jsdoc-to-markdown.