Mirza Leka

Posted on Mar 3

Learn how to document JavaScript/TypeScript code using JSDoc & Typedoc

#javascript #typescript #typedoc

In this blog, you'll learn how to document your JS/TS code, how to give more context to your functionalities using JSDoc, and how to generate documentation files using Typedoc.

Setting up the project

Create a new project using npm:

> npm init -y

For this blog I've created a small app (download code) containing 3 files:

src/app.js
src/models/user.mjs
src/models/todo.mjs

Then update the package.json file to use ES Modules:

{
  "name": "js-docs",
  "version": "1.0.0",
  "description": "",
  "main": "app.js",
  "type": "module", // <--- this part
  "scripts": {
    "start": "node ./src/app.js",
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Basic Todo class

// todo.mjs
export default class Todo {
  id;
  title;
  description;
  isCompleted;

  constructor(id, title, description, isCompleted) {
    this.id = id;
    this.title = title;
    this.description = description;
    this.isCompleted = isCompleted;
  }
}

Basic User class

A user holds a list of Todos.

// user.mjs
export default class User {
  id;
  username;
  #todos = []; // #todos is a private class member

  constructor(id, username) {
    this.id = id;
    this.username = username;
  }

  addTodo(todo) {
    this.#todos.push(todo);
  }

  getTodos() {
    return this.#todos;
  }
}

Now let's put them together.
Back in app.js create an instance of user, followed by an instance of todo.

// app.js
import Todo from './models/todo.mjs';
import User from './models/user.mjs';

const todo = new Todo(1, 'Must write a new blog', 'Something awesome', false);
const user = new User(1, 'Mirzly');

Now assign this todo to a user:

import Todo from './models/todo.mjs';
import User from './models/user.mjs';

const todo = new Todo(1, 'Must write a new blog', 'Something awesome', false);
const user = new User(1, 'Mirzly');

user.addTodo(todo);
const userTodos = user.getTodos();

console.log('userTodos :>> ', userTodos);

If you run the app (using npm start), you should see user todos printed in the console:

-docs>npm start

> js-docs@1.0.0 start
> node ./src/app.js

userTodos :>>  [
  Todo {
    id: 1,
    title: 'Must write a new blog',
    description: 'Something awesome',
    isCompleted: false
  }
]

Adding Docs

If you hover over the Todo or User class, there is very little information about either class.

And since JavaScript doesn't have type safety, there is no IntelliSense to tell you what methods are available on the object and what parameters you can pass to them.

This is where JSDoc comes to save the day.

In JavaScript, you can generate docs by simply typing /** and hitting enter. The Visual Studio Code then sets up a wrapper:

/**
 * 
 */

Inside you can describe your classes, interfaces, functions, their properties, and return types however you like:

/**
 * Creates a new User
 * @property {number} id - User Id
 * @property {string} username - User username
 * @method addTodo {Function} - Adds new todo
 * @method getTodos {Function} - Retrieves all todos
 */
export default class User { 
  // ...

  /**
   * Used to add a new todo
   * @param {Todo} todo - New todo
   * @returns {void} - Does not return anything
   */
  addTodo(todo): void {
    this.#todos.push(todo);
  }

  /**
   * Used to retrieve all todos
   * @returns {Todo[]} - Todos list
   */
  getTodos() {
    return this.#todos;
  }

}

Now if you hover over the User class you should see more info.

This is also applied to the methods that you document:

How cool is that?

TypeDoc

Now let's add TypeDoc - Documentation generator for TypeScript.
That said, you need to initialize a TypeScript project:

Setting up TypeScript

> tsc -init

Now paste the following config into the newly generated tsconfig.json file:

{
  "compilerOptions": {
    "target": "es2016",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "module": "commonjs",
    "outDir": "./dist",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  }
}

Changing file structure

Now rename all your .js/.mjs files to .ts:

src/app.ts
src/models/user.ts
src/models/todo.ts

Also be sure to remove the "type": "module" from the package.json file as that can confuse Node.js when running the files.

Fixing formatting

TypeScript will complain about the lack of "types" in the files. Here are the changed files:

user.ts

import Todo from './todo';

/**
 * Creates a new User
 * @property {number} id - User Id
 * @property {string} username - User username
 * @method addTodo {Function} - Adds new todo
 * @method getTodos {Function} - Retrieves all todos
 */
export default class User {
  id: number;
  username: string;
  #todos: Todo[] = [];

  constructor(id: number, username: string) {
    this.id = id;
    this.username = username;
  }

  /**
   * Used to add a new todo
   * @param {Todo} todo - New todo
   * @returns {void} - Does not return anything
   */
  addTodo(todo: Todo): void {
    this.#todos.push(todo);
  }

  /**
   * Used to retrieve all todos
   * @returns {Todo[]} - Todos list
   */
  getTodos(): Todo[] {
    return this.#todos;
  }
}

todo.ts

/**
 * Creates a new Todo
 * @property {number} id - Todo id
 * @property {string} title - Todo title
 * @property {string} description - Todo description
 * @property {boolean} isCompleted - Todo isCompleted status
 */
export default class Todo {
  id: number;
  title: string;
  description: string;
  isCompleted: boolean;

  constructor(id: number, title: string, description: string, isCompleted: boolean) {
    this.id = id;
    this.title = title;
    this.description = description;
    this.isCompleted = isCompleted;
  }
}

Running the app (TS)

You need to install ts-node to run the Typescript files:

> npm i -D ts-node

Now add ts-node to the start script in the package.json file:

{
  "name": "js-docs",
  "version": "1.0.0",
  "description": "",
  "scripts": {
    "start": "ts-node ./src/app.ts"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "ts-node": "^10.9.2"
  }
}

Running the app using npm start should print the same result as before.

Adding TypeDoc

Firstly, install Typedoc using npm:

> npm i typedoc -D

Then update the tsconfig.json file with Typedoc configuration:

{
  "compilerOptions": {...},
  "typedocOptions": {
    "entryPoints": [
      "src/models/*.ts" // <--- take everything from this location
    ],
    "out": "docs/typedoc" // <--- output directory
  }
}

Lastly, add a script that is used from running Typedoc

  "scripts": {
    "start": "ts-node ./src/app.ts",
    "type-docs": "typedoc" // <-- reads config from tsconfig.json
  },

Run the script using:

> npm run type-docs

[info] Documentation generated at ./docs/typedoc

This will generate HTML docs page in the specified path ("out": "docs/typedoc") that you can open in your web browser.

More complex projects will have better-detailed docs.

That's all from me today.
If you'd like to learn more make sure to check out my other blog as well on Medium and follow me on Twitter to stay up to date with my content updates.

Bye for now 👋