![[JavaScript/TypeScript] JSDoc/TypeDoc Cheatsheet](https://images.ctfassets.net/ct0aopd36mqt/wp-thumbnail-c571649dbbcec5de8ede099370219c46/4ea60fd4ac865c70d3c2e8f2589acc3a/ts-eyecatch.png?w=3840&fm=webp)
[JavaScript/TypeScript] JSDoc/TypeDoc Cheatsheet
This article was published more than one year ago. Please be aware that the information may be outdated.
This page has been translated by machine translation. View original
TypeScript with TypeDoc using JSDoc documentation
Installation
npm install typedoc
Output
typedoc --entryPointStrategy expand SOURCE_DIR --out OUT_DIR,
Description
Syntax: @description description text
Text written at the beginning of a JSDoc comment without a block tag is treated as @description.
/**
* Outputs the string foo
*/
export function foo() {
console.log('foo');
}
When writing elsewhere in the comment, explicitly add @description.
/**
* @returns {string} string foo
* @description Returns the string foo
*/
export function foo() {
return 'foo';
}
Return value
Syntax: @returns [{type}] [description]
/**
* Returns the string foo
* @returns {string} string foo
*/
export function foo() {
return 'foo';
}
Arguments
Syntax: @param [{type}] [parameter name [description]]
/**
* @param {string} userName User's name
*/
export function sayHello(userName) {
alert('Hello ' + userName);
}
Properties of classes and namespaces
Syntax: @property [{type}] [property name [description]]
/**
* Coordinate
* @property {number} x X-axis value
* @property {number} y Y-axis value
* @property {number} distance Calculates distance from the argument Point
*/
export class Point {
readonly x: number;
readonly y: number;
constructor(x: number, y: number) {
this.x = x;
this.y = y;
}
distance(p: Point): number {
return Math.hypot(this.x - p.x, this.y - p.y);
}
}
Enumeration type
Syntax: @enum [{type}]
You can explain each value by inserting doc comments just before each value.
/**
* Seasons
* @enum {string}
*/
export const SEASONS = {
/** Spring */
SPRING: '春',
/** Summer */
SUMMER: '夏',
/** Autumn */
AUTUMN: '秋',
/** Winter */
WINTER: '冬'
};
Exceptions that may be thrown
Syntax: @throws [{type}] [description]
/**
* Returns the argument if it is a number
* @throws {TypeError} If the argument is not a number
*/
export function foo(x: any): number {
if (typeof x !== 'number') {
throw new TypeError('x is not a number');
}
return x;
}
Example demonstration with embedded code block
Syntax: @example [<caption>Caption</caption>]
Everything after the line break until the next block tag is treated as a code block.
/**
* Returns the string foo
* @examle
* // returns 'foo'
* console.log(foo());
*/
export function foo() {
return 'foo';
}
You can add a caption using <caption></caption> after @example.
/**
* Returns the argument if it is a number
* @throws {TypeError} If the argument is not a number
* @example <caption>Success example</caption>
* foo(1); // 1
* @example <caption>Failure example</caption>
* foo('a'); // TypeError: x is not a number
*/
export function foo(x: any): number {
if (typeof x !== 'number') {
throw new TypeError('x is not a number');
}
return x;
}
Additional information ※ TypeDoc only
Syntax: @remarks explanation
Adds supplementary information to the description.
/**
* Hogehoge fugafuga
* @remarks Additional information is written here
*/
export function foo() {}
