[JavaScript] JSDoc 작성 방법

Published: by Creative Commons Licence

참고 문서

개요

JSDoc란 함수나 메서드, 프로토타입, (자바의) 클래스 등의 선언부(혹은 정의부) 바로 위에 작성하는 코멘트 블록(Multiline comment)을 말한다. 관례상 일반적인 코멘트 블록과 다르게 /**로 시작한다. 작성해두면 IDE에서 툴팁으로 코멘트 내용을 미리 보여준다던지 등의 소소한 이점도 있다.

간단히 말해서 자바의 Javadoc처럼 API 문서(API Documentation) 생성을 위한 특수한 코멘트 블록이라 할 수 있다.

doc가 뭔데

우리말로는 '문서 코멘트' 정도로 부르면 된다.

영문으로는:

  • Documentation comments (IntelliJ)
  • Doc comments

정도로 쓰면 될 것 같음.

JSDoc를 문서로 내보내기

Node.js 패키지 JSDoc를 설치해 실행하면 된다.

# JSDOc 설치
npm install --save-dev jsdoc

# 파일로 만들기
npm exec jsdoc ./src/test/js-doc-test.js

이렇게 하고 out 디렉터리를 확인해보자.

작성 방법

/**
 * @param {Date} myDate The date
 * @param {string} myString The string
 * @param {boolean} myFlag The flag
 * @param {string|number} myArg I dunno
 * @returns {string|Object} return string or number
 */
function myFn(myDate, myString, myFlag, myArg) {
  // do stuff
}

/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {Promise} Promise object represents the sum of a and b
 */
function sumAsync(a, b) {
  return Promise.resolve(a + b);
}

요딴식으로 하면 됨.

블록 태그와 인라인 태그

/**
 * Set the shoe's color. Use {@link Shoe#setSize} to set the shoe size.
 *
 * @param {string} color - The shoe's color.
 */
Shoe.prototype.setColor = function (color) {
    // ...
};

@param이 블록 태그고 {@link}가 인라인 태그다. 현재(2024-02-19) 인라인 태그는 @link(별칭: @linkcode, @linkplain)와 @tutorial만 지원한다.

파일 doc

예전에는 대체로 이렇게 하는 경우도 많았는데:

/*!
 * 이 편지는 영국에서 최초로 시작되어 일년에 한바퀴를 돌면서 받는 사람에게 행운을 주었고...
 */

JSDoc에서는 @file 태그를 이용하라고 한다:

/**
 * @file 이 편지는 영국에서 최초로 시작되어 일년에 한바퀴를 돌면서 받는 사람에게 행운을 주었고...
 * @since 2023-09-19
 */

데이터 타입

부수효과로 편집기에 따라 툴팁으로 파라미터의 타입이 보인다거나, 자동 완성 기능이 타입에 맞춰서 알아서 된다거나 하는게 있다.

구성요소의 타입을 특정할 수 없는 배열이면 Array 혹은 any[]라고 적는다. 반대의 경우엔 해당 타입과 대괄호[]를 적는다. 가령 string 타입의 배열이면 string[]이다.

자동완성되는 걸 보면 이런 것도 가능:

@returns {Promise<void>}

원시 타입(number, string, boolean, symbol)을 제외한 나머지는 프로토타입 이름 그대로 써주면 된다. e.g., Object, Function, Document, Node, Window, …

*는 모든 타입이 올 수 있음을 나타낸다.

OR

여러 타입을 허용하는 경우 이렇게 쓴다:

/**
 * @returns {null|string|*} null 혹은 string 혹은 any를 반환한다는 뜻 (사실상 쓰나마나다 🤭)
 */
function getAny() {
  //... 
}

상수나 변수의 데이터 타입

@type을 쓴다.

/**
 * 푸-바
 * 
 * @type {string}
 */
const foo = 'bar';

구조 분해 할당을 사용하는 함수 파라미터는?

// 소스 출처: https://stackoverflow.com/questions/36916790/document-destructured-function-parameter-in-jsdoc
/**
 * My cool function.
 *
 * @param {Object} obj - An object.
 * @param {string} obj.prop1 - Property 1.
 * @param {string} obj.prop2 - Property 2.
 */
function willDestroyU({prop1, prop2}) {
  // Do something with prop1 and prop2
}

스펙 정의는 여기를 참고.

마크다운 플러그인 사용하기

JSDoc는 기본적으로 줄 바꿈을 지원하지 않아서, 줄 바꿈이나 목록을 표현하고 싶다면 HTML 태그를 강제로 사용하거나 마크다운 플러그인을 적용해야 한다.

{
  "plugins": ["plugins/markdown"]
}

위처럼 작성된 설정 파일을 하나 만들고, 빌드할 때 옵션으로 해당 설정 파일의 경로를 지정해주면 끗:

# ./src에 있는 소스 파일을 대상으로 빌드. 빌드 경과는 ./doc 아래에 생성한다. 이 때 설정파일로 ./confi/jsdoc-config.json 파일을 사용함
npm jsdoc ./src --destination ./doc --configure ./conf/jsdoc-config.json

이렇게하면 코멘트를 마크다운 서식으로 인식한다.

/**
 * @file 코파일럿 테스트용 파일
 * 
 * #### 단축키
 * 
 * - `alt + \`: 코파일럿 발동
 * - `tab`: 코파일럿 제안 선택
 * 
 * ...
 * function fn() {
 *  console.log('Hello, world!');
 * }
 * ```
 *
 * (생략)
 */

기타 블록 태그들

@description, @desc

함수나 변수의 설명을 작성할 때 사용한다. 이 태그를 명시하면 태그가 적용되지 않은 코멘트는 무시된다(@file도 같이 무시하는 걸로 보임). 만약 태그가 없는 설명 코멘트가 다른 태그들보다 위에 있을 경우 @desc를 생략할 수 있다.

파일 코멘트 영역에선 이 태그 대신 @file을 사용할 것.

@param

TODO

@returns

TODO

@deprecated

/**
 * @deprecated since version 2.0
 */