API docs from JSDoc
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:
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:
/**
* 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:
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:
<% 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:
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.