JSDoc은 JavaScript 코드에 주석을 달아 API 문서를 자동으로 생성하기 위한 표준 형식 중 하나이다. JSDoc 주석은 /** ... */ 형태의 블록 주석 안에 @param, @returns, @type 등과 같은 태그를 사용해 함수, 변수, 클래스 등의 시그니처와 동작을 설명한다. 이러한 주석은 JSDoc 툴(예: jsdoc CLI)이나 TypeScript, Closure Compiler 등 다양한 문서 생성 도구에 의해 파싱되어 HTML, Markdown 등 다양한 형식의 문서로 변환된다.
주요 특징
-
타입 주석
@param {string} name– 매개변수의 이름과 타입을 명시.@returns {number}– 반환값의 타입을 지정.
-
구조화된 메타데이터
@typedef와@property를 이용해 복합 객체 타입을 정의.@enum을 통해 열거형을 선언.
-
코드 인텔리센스 지원
- IDE(Visual Studio Code, WebStorm 등)와 연동해 자동완성, 타입 힌트를 제공한다.
- JSDoc 주석은 TypeScript 선언 파일(
.d.ts) 생성에도 활용된다.
-
다양한 출력 포맷
- 기본적으로 HTML 문서가 생성되며, 플러그인이나 템플릿을 통해 PDF, Markdown 등으로 변환 가능하다.
역사 및 배경
- JSDoc은 2002년 Douglas Crockford가 제안한 JavaScript 코드 주석 표준으로 시작되었다.
- 2005년에는 JSDoc 2.x가 발표되어 태그 체계와 파싱 규칙이 정형화되었으며, 이후 지속적인 업데이트를 거쳐 현재는 JSDoc 3.x 버전이 널리 사용되고 있다.
사용 예시
/**
* 두 수를 더한 값을 반환한다.
*
* @param {number} a 첫 번째 피연산자
* @param {number} b 두 번째 피연산자
* @returns {number} a와 b의 합
*/
function add(a, b) {
return a + b;
}
위와 같은 주석을 포함한 코드는 jsdoc 명령어를 실행하면 함수 add에 대한 설명과 매개변수·반환값 정보가 포함된 문서가 자동 생성된다.
도구 및 생태계
- jsdoc: 공식 CLI 도구로, 커맨드라인에서
jsdoc src/ -d docs/와 같이 실행한다. - ESDoc, TypeDoc: JSDoc 스타일 주석을 지원하며, 추가적인 기능(예: 테스트 커버리지 연동)도 제공한다.
- IDE 플러그인: 대부분의 현대 JavaScript IDE는 JSDoc 주석을 인식하여 자동완성 및 타입 검증을 지원한다.
적용 범위
JSDoc은 오픈소스 라이브러리, 프론트엔드 프레임워크, Node.js 모듈 등 JavaScript 기반 프로젝트 전반에 걸쳐 사용된다. 특히 타입 정보를 명시함으로써 런타임 오류를 사전에 방지하고, 협업 시 API 가용성을 높이는 데 기여한다.
