TypeScript + JSDoc = better-docs

better-docs was created as a simple (yet beautiful) theme for JSDoc generated documentation. Over the last months, at SoftwareBrothers, we’ve added it so many features that now it is rather a documentation toolbox for JavaScript than just a theme.

Our latest addition is TypeScript support and, in this brief article, I will show you how you can use it in your project. I would like to know your opinion about it —so you can either star it on GitHub or write a hate-like comment :). I will strongly appreciate either of that.

JSDoc — what is that?

For those of you who don't know what JSDoc is — it is a markup language which is used to describe JavaScript code.

Example of describing a method with JSDoc:

/**
 * Renders an entire login page with email and password fields
 * using {@link Renderer}.
 *
 * Used by external plugins
 *
 * @param  {Object} options
 * @param  {String} options.action          login form action
 * @param  {String} [options.errorMessage]  optional messaga
 * @return {Promise<string>}                HTML of the page
 */
static async renderLogin({ action, errorMessage }) {
  return loginTemplate({ action, errorMessage })
}

Why would we use that? In the pre-TypeScript era, it was the only place where we could obtain information about the types.

But most of all it is used to generate a documentation page for your project.

If you want to know how to set up the JSDoc in your project — take a look at this short video: https://youtu.be/Yl6WARA3IhQ or check out the project page

JSDoc with TypeScript? Why?

I can point out at least 3 reasons for using JSDoc + better-docs + TypeScript

1. Documentation generated by better-docs looks very well (screenshots below)
2. It is based on JSDoc — a stable tool created a long time ago with lots of plugins and templates allowing you to selectively document parts of your code
3. It works with both .js and .ts files so if you are still in the migration phase, this tool is for you.
4. … and it documents your React/Vue components as well (with a live preview).

Screenshots

How it works

I won’t tell you how to install it — you can check that out in the repo readme. Instead, let’s see how it works so you can verify if it is worth trying.

Convert type to “@typedef”

JSDoc has a very nice feature of defining types with @typedef tag. So better-docs changes all your documented type aliases to JSDoc “@typedef” definitions.

Let me show you an example. Let’s say you have a type ActionRequest documented like this:

/**
 * ActionRequest
 * @memberof Action
 * @alias ActionRequest
 */
export type ActionRequest = {
  /**
   * parameters passed in an URL
   */
  params: {
    /**
     * Id of current resource
     */
    resourceId: string;
    /**
     * Id of current record
     */
    recordId?: string;
    /**
     * Name of an action
     */
    action: string;
    [key: string]: any;
  };
  /**
   * POST data passed to the backend
   */
  payload?: Record<string, any>;
  /**
   * Elements of query string
   */
  query?: Record<string, any>;
  /**
   * HTTP method
   */
  method: 'post' | 'get';
}

better-docs will change it to

/**
 * ActionRequest
 * @memberof Action
 * @alias ActionRequest
 * @typedef {object} ActionRequest
 * @property {object} params   parameters passed in an URL
 * @property {string} params.resourceId   Id of current resource
 * @property {string} [params.recordId]   Id of current record
 * @property {string} params.action   Name of an action
 * @property {any} params.{...}
 * @property {Record<string, any>} [payload] POST data passed to the
                                             backend
 * @property {Record<string, any>} [query] Elements of query string
 * @property {'post' | 'get'} method       HTTP method
*/

And this will be parsed by JSDoc and printed as a table like this:

nice — isn't it?

Convert TypeScript interfaces to “@interface” tags

All your documented interface definitions from TypeScript are converted to “@interface” — its JSDoc counterpart.

Where “@typedef” in JSDoc is rather concise — “@interface” tags are more detailed when it comes to rendered documentation.

You document it the same way, but JSDoc will generate an entire page where each element of the interface will have its own section.

As an example take a look at this documented interface and the corresponding .ts file

Transpile to javascript

Lastly, better-docs will transpile all your .ts files to regular JavaScript. It prevents JSDoc from throwing errors and ensures that all your regular jsdoc comments will be parsed as well.

Summary

And this is it — as simple as that.

We will further improve the tool as we document all of our projects at SoftwareBrothers and we want to have one standard for both JavaScript and TypeScript codebases.

Alternatives

Of course, better-docs is not the only way to document the TypeScript code. There is a quite a popular tool http://typedoc.org/ — so when you have just .ts files — it’s worth trying.

Furthermore, there is a new standard called TSDoc which is supported by Microsoft: https://github.com/microsoft/tsdoc. But when you visit their playground (https://microsoft.github.io/tsdoc/) and paste the type definition for ActionRequest which I presented before — it generates nothing :(.