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

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 <[e-mail]>.

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