documenting-js.md

Documenting JS/TS Code using JSDoc & Typedoc

Initialize the Node.js project using NPM:

> npm init -y

Update the package.json to use ES Modules

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

Set up folder structure

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

Basic Todo class

// todo.mjs

/**
 * 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;
  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

/**
 * 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;
  username;
  #todos = []; // #todos is a private class member

  constructor(id, username) {
    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) {
    this.#todos.push(todo);
  }

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

Main file (app,js)

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

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);

JSDoc docs appearing in VSC Editor

documenting-ts.md

Documenting TypeScript using TSDoc & TypeDoc

Initialize the TypeScript project:

> tsc -init

Install dependencies

> npm i ts-node typedoc -D

Update TSConfig

{
  "compilerOptions": {
    "target": "es2016",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "module": "commonjs",
    "outDir": "./dist",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  },
  "typedocOptions": {
    "entryPoints": [
      "src/models/*.ts"
    ],
    "out": "docs/typedoc"
  }
}

Update Package.json

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

Update project files:

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

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);

// 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;
  }
}

// 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;
  }
}

Generate the docs

> npm run type-docs

Typedoc generated docs