![[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 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() {}
