@kamikazept/jsdoc-md

A Node.js CLI to analyze source JSDoc and generate documentation under a given heading in a markdown file (such as readme.md).

Setup

To try it out with npx run:

npx @kamikazept/jsdoc-md --help

To install @kamikazept/jsdoc-md from npm as a dev dependency run:

npm install @kamikazept/jsdoc-md --save-dev
yarn add @kamikazept/jsdoc-md --dev

Add a script to your package.json:

{
  "scripts": {
    "jsdoc": "jsdoc-md"
  }
}

Then run the script to update docs:

npm run jsdoc

CLI

For detailed CLI usage instructions, run npx jsdoc-md --help.

| Option | Alias | Default | Description | | :-- | :-- | :-- | :-- | | --source-glob | -s | **/*.{mjs,js} | JSDoc source file glob pattern. | | --markdown-path | -m | readme.md | Path to the markdown file for docs insertion. | | --target-heading | -t | API | Markdown file heading to insert docs under. |

API

Table of contents

• function jsdocMd
  • Examples

function jsdocMd

Scrapes JSDoc from files to populate a markdown file documentation section.

| Parameter | Type | Description | | :-- | :-- | :-- | | options | Object? | Options. | | options.sourceGlob | string? = **/*.{mjs,js} | JSDoc source file glob pattern. | | options.markdownPath | string? = readme.md | Path to the markdown file for docs insertion. | | options.targetHeading | string? = API | Markdown file heading to insert docs under. |

Examples

Customizing all options.

const { jsdocMd } = require('jsdoc-md')

jsdocMd({
  sourceGlob: 'index.mjs',
  markdownPath: 'README.md',
  targetHeading: 'Docs'
})

Caveats

No code inference

Missing JSDoc tags are not inferred by inspecting the code, so be sure to use all the necessary tags.

/**
 * The number 1.
 * @kind constant
 * @name ONE
 * @type {number}
 */
const ONE = 1

Tag subset

A JSDoc tag subset is supported:

• @kind
• @name
• @type
• @prop
• @param
• @returns
• @see
• @example
• @ignore

With the full set of JSDoc tags there is a confusing number of ways to document the same thing. Examples TWO and THREE use unsupported syntax:

/**
 * My namespace.
 * @kind namespace
 * @name MyNamespace
 */
const MyNamespace = {
  /**
   * The number 1.
   * @kind constant
   * @name MyNamespace.ONE
   * @type {number}
   */
  ONE: 1,

  /**
   * The number 2 (unsupported).
   * @constant {number} TWO
   * @memberof MyNamespace
   */
  TWO: 2,

  /**
   * The number 3 (unsupported).
   * @const MyNamespace.THREE
   * @type {number}
   */
  THREE: 3
}

Namepath prefixes

JSDoc namepath prefixes are not supported:

• module:
• external:
• event:

Namepath special characters

JSDoc namepath special characters with surrounding quotes and backslash escapes (e.g. @name a."#b"."\"c") are not supported.

Inline tags

One JSDoc inline tag link syntax is supported for namepath links in JSDoc descriptions and tags with markdown content: [`b` method]{@link A#b}. Use normal markdown syntax for non-namepath links.

Other inline tags such as {@tutorial} are unsupported.

Example content

@example content outside <caption /> (which may also contain markdown) is treated as markdown. This allows multiple code blocks with syntax highlighting and explanatory content such as paragraphs and images. For example:

/**
 * Displays a message in a native popup window.
 * @kind function
 * @name popup
 * @param {string} message Message text.
 * @example <caption>Say `Hello!` to the user.</caption>
 * This usage:
 *
 * ```js
 * popup('Hello!')
 * ```
 *
 * Displays like this on macOS:
 *
 * ![Screenshot](path/to/screenshot.jpg)
 */
const popup = message => alert(message)