[JSDoc] JSDoc이란 ?

JSDoc이란?

JSDoc은 Javadoc 또는 phpDocumentor와 유사한 javascript용 API 문서 생성기이다. 코드 자체와 함께 소스코드에 직접 문서 주석을 추가한다. 

 

VSCode에서 순수한 자바스크립트 소스코드에 @ts-check 를 주석으로 추가하면 typescript처럼 타입 및 에러 체크가 가능하다.

 

주석을 사용하여 함수에 대해 설명하거나, @ts-check를 이용하면 설명과 어느정도의 에러 체크가 가능하지만, JSDoc의 태그를 사용하여 더 많은 정보를 제공할 수 있다. 예를 들어 함수가 클래스의 생성자인 경우 아래와 같이 사용할 수 있다.

/** 이 함수는 Book클래스의 생성자이다. */
function Book(title, author) {}

/**
 * 책을 의미하는 함수이다.
 * @constructor
 * @param {string} title - 책의 제목
 * @param {string} author - 책의 저자
 */
function Book(title, author) {}

 

변수 타입

/** @type {string} */
let str;

/** @type {number} */
let num;

/** @type {boolean} */
let bool;

/** @type {*} */
let any;

/** @type {?} */
let unknown;

/** @type {number[]} */
let nums;

/** @type { {id: number, content: string, completed: boolean} } */
let obj;

/** @type {string|number} */
let union;

/** @type {Array<{ id: number, content: string, completed: boolean }>} */
let generic;

 

함수 타입

/**
 * @description TypeScript syntax를 사용하는 방법
 * @description 두 수의 합을 구한다.
 * @type { (a: number, b: number) => number }
 */
 const add = (a, b) => a + b;

/**
 * @description Closure syntax를 사용하는 방법
 * @description 두 수의 곱을 구한다.
 * @type { function(number, number): number }
 */
 const multiply = (a, b) => a * b;

/**
 * @description JSDoc syntax를 사용하는 방법
 * @description 두 수의 차를 구한다.
 * @param {number} a - the first thing
 * @param {number} b - the second thing
 * @returns {number}
 */
 const subtract = (a, b) => a - b;
 
 /**
 * @param {string}  p1 - A string param.
 * @param {string=} p2 - An optional param (Closure syntax)
 * @param {string} [p3] - Another optional param (JSDoc syntax).
 * @param {string} [p4="test"] - An optional param with a default value
 * @return {string} This is the result
 */
function stringsStringStrings(p1, p2, p3, p4) {
  return p1 + p2 + p3 + p4;
}

@param은 타입 구문인 @type과 동일하게 사용할 수 있다. 단, @param은 매개변수 이름을 추가할 수 있고 매개변수는 이름을 대괄호로 감싸서 선택적 매개변수임을 명시할 수 있다.

 

타입 정의

/**
 * 할일
 * @typedef {Object} Todo
 * @property {number} id - 할일 id
 * @property {string} content - 할일 내용
 * @property {boolean} completed - 할일 완료 여부
 */

/**
 * 할일 목록
 * @type {Todo[]}
 */
const todos = [
  { id: 1, content: 'HTML', completed: false },
  { id: 2, content: 'CSS', completed: true },
  { id: 3, content: 'Javascript', completed: false },
];

@typedef는 복잡한 타입을 정의할 때 사용한다.

Callback

// @ts-check

// TypeScript syntax를 사용하는 방법
/**
 * @typedef { (data: string, index?: number) => boolean } Predicate1
 */

// Closure syntax를 사용하는 방법
/**
 * @typedef { function(string, number=): boolean } Predicate2
 */

// JSDoc syntax를 사용하는 방법
/**
 * @callback Predicate3
 * @param {string} data
 * @param {number} [index]
 * @returns {boolean}
 */


/** @type {Predicate1} */
const ok = s => !(s.length % 2);

@callback은 @typedef와 유사하지만 object타입 대신 특정한 function 타입을 지정한다.

 

 

https://ko.wikipedia.org/wiki/JSDoc
https://jsdoc.app/about-getting-started.html
https://poiemaweb.com/jsdoc-type-hint