Guideline for JSDoc

Overview

For role of type checker Typescript is a cool way. However, in some cases, it's excessive. The codes should be compiled whenever codes has been changed. It means that it doesn't require extra dependencies. Because of some reasons, some projects are only using JSDoc. Moreover, many IDE such as WebStorm and VSCode supports type checker. JsDoc comments should be beginning with /* or /**.

Common tags

Keyword starts with "@". Following table describes commonly using keywords. This article will not display examples about all tags, but click the link to see more tags and details.

Tags	Description
@param	parameter values for function
@return	return value
@type	type of variable
@const	const of variable
@typedef	custom types
@property	properties of class
@link	link to another item in the documentation.
@throws	what errors could be thrown.
@alias	treat a member as if it had a different name
@name	the name of an object.
@private	private variable or function
@deprecated	document that this is no longer the preferred way.
@author	the author of function, class etc
@constructs	indicates this function is constructor
@readonly	read-only field, function variable
@todo	task to be completed
@enum	a collection of related properties.
@override	a symbol overrides its parent.

@param and @return

The parameter may also be declared optional by surrounding the name with square brackets . @param can be three types

Primitive (string, number ...)
global or imported
Declared with typedef

@param tag provides the name, type and description in turn

/**
 * @param {string=} n - Optional
 * @param {string} [n] - Optional
 * @param {(string|number)} n - Multiple types
 * @param {*} n - Any type
 * @param {...string} n - Repeatable arguments
 * @param {string} [n="hi"] - Optional with default
 * @param {string[]} n - Array of strings (Type is changeable)
 */

@return keyword can indicate types surrounding the name with square brackets

/**
 * @return {Promise<string[]>} n - Promise fulfilled by array of strings
*/

Example 1 - Normal function

/**
 * This is exmaple function
 * @param {string} a - Example string param
 * @param {string | number } b - Example
 * @param {string} [c="hello"] c - string paramter with default "hello"
 * @return {*} any type can be returned
 */
function exampleFun(a, b, c) {
  // ...
  return d
}

Example 2 - Promise

/**
 * This is exmaple function
 * @return {Promise<number>} return prmosie
 */
async function exampleFun() {
  return 100
}

@type, @typedef, and @property

@type tag uses the same type syntax as @param, but there is no parameter name. @typedef tag is useful for documenting custom types, particularly if you wish to refer to them repeatedly

Example for @type

/** @type {(string)} */
var foo
/** @type {number} */
var bar = 1

Example 1 - @type and @property

/**
 * Read a book taken by parameter
 * @typedef {Object} Book
 * @property {string} title - The title
 * @property {string} author - The author
 */
function read(book) {}

Example 2 - importing types

/**
 * @typedef {import('./Foo').default} Foo
 * @param {Foo} foo
 */
function fooFunc(foo) {}

Example 3 - use @link

/**
 * Read a book taken by parameter
 * @param {Book} song - The {@link Book} to be read
 */
function read(book) {}

@private, @override and @constructor

The @private, @override, and @constructor tags are usually used in class. There is not only @prviate but also more property modifiers such as @public and @protected.

Example

/**
 * @class
*/
class Product {
  /**
   * @constructor
   */
  constructor() {
    /** @private */
    this.name = 0;
    /** @protected */
    this.price = 0;
    /** @public */
    this.description = 0;
  }
}

Example - `@override`

export class P {
  exampleFunc() { }
}
class C extends P {
  /** @override */
  exampleFunc() { }
}

Other examples

Shortly mention some examples about some tags.

@const

@const typically represents it's constant variable.

/** @const {number} */
const num = 1

@readonly

@const indicates the properties won't be modified with any reason.

/** @readonly */
class Product {
  constructor() {
    /** @readonly */
    this.name = 0
  }
}

@author and @deprecated

@author indicates who makes this item. @deprecated indicates this item is no longer usable.

/**
 * @author it's me
 * @deprecated
 */
function exampleFunc() {}

@enum

@enum tag allows to create a static properties consisting of same type.

/** @enum {number} */
const VideoStatus = {
  LOAD: 0,
  PLAYING: 1,
  PAUSE: 2,
};

@alias and @name

@alias tag and @name play a similar role for renaming

/**
 * a function.
 * @name b
 */
function a() {}

/**
 * a function.
 * @alias b
 */
function a() {}

@todo

/** @todo - Add an example logic */
function exampleFunc() {}