API docs from JSDoc

Page content:

Postdoc can turn the JSDoc comments in your JavaScript code into pages, so your API reference is written next to the code it describes. The API Reference of this site is generated this way from Postdoc's own source.

Turn it on

Point apidocs.source at the folder with your code:

postdoc.config.jsjs
export default {
  apidocs: {
    source: './src'
  }
};

Every .js file in that folder with a documentation comment becomes a page. With requireName: true in apidocs, only the files with a comment that has a @name tag do, which keeps helper modules out:

js
/**
 * Formats a price for display.
 *
 * @name formatPrice
 * @param {number} amount The price in cents.
 * @param {string} [currency] An ISO currency code. Defaults to `EUR`.
 * @returns {string} The formatted price.
 * @example
 * ```js
 * formatPrice(1999, 'USD'); // "$19.99"
 * ```
 */
export function formatPrice(amount, currency = 'EUR') {
  // ...
}

Descriptions and examples are Markdown, so they can contain links, lists and code blocks. Wrap an example in a fenced code block, as above, to get syntax highlighting.

Comments that start with /*! or have an @ignore tag are skipped, and so are the folders and files listed in ignore.apidocs. node_modules and test folders are skipped by default.

URLs

A file's page gets the file's path inside source, with .html instead of .js: with source: './src', src/utils/price.js becomes /utils/price.html. To choose other URLs, give a createUrl function. It receives the path inside source, starting with a /, and returns the URL:

postdoc.config.jsjs
export default {
  apidocs: {
    source: './src',

    createUrl(filePath) {
      return '/api' + filePath.replace(/\.js$/, '.html');
    }
  }
};

The layout

API pages use one layout, layouts/apidocs.ejs by default, which you can change with apidocs.layoutName. In it, page.comments holds the file's comments, in order, and page.commentsSourcePath the path of the file.

Each comment has these properties:

Property Contents
name From @name, or the name of the function or variable that follows the comment
description The description, as HTML
kind From @kind, or function for @function and @method
parameters One object per @param, with name, types, optional and description
returns From @returns: an object with type and description, or null
example One string per @example, as written
exampleHtml One HTML block per @example, compiled as Markdown
since From @since
see One string per @see
aliases One string per @alias
internal true when the comment has @internal

A minimal layout:

html
<% for (const item of page.comments) { %>
  <section>
    <h2><%= item.name %></h2>
    <%- item.description %>

    <% if (item.parameters.length) { %>
      <h3>Parameters</h3>
      <ul>
        <% for (const parameter of item.parameters) { %>
          <li>
            <code><%= parameter.name %></code> (<%= parameter.types %><%= parameter.optional ? ', optional' : '' %>):
            <%- parameter.description %>
          </li>
        <% } %>
      </ul>
    <% } %>

    <% for (const example of item.exampleHtml) { %>
      <%- example %>
    <% } %>
  </section>
<% } %>

If your project has no API layout, the theme's is used. The default theme's lists each comment's name and description, which is a starting point for your own.

Custom tags

To use a tag Postdoc doesn't know, add a function for it under apidocs.tags. The function receives the tag, the whole comment and the properties collected so far, and returns properties to add to the comment:

postdoc.config.jsjs
export default {
  apidocs: {
    source: './src',

    tags: {
      deprecated(tag) {
        return { deprecated: tag.string || true };
      }
    }
  }
};

With that, @deprecated Use formatMoney instead. gives the comment a deprecated property that your layout can show.

Edit this page on GitHub