JSDoc을 통해 JavaScript API 문서 만들기

최근 사내 신규 개발 작업이 끝난 뒤 배포를 앞두고 산출물을 검토하는 중, 400여 개의 Interface 함수를 설명하는 API 매뉴얼 페이지를 작성하는 업무가 주어졌다. 각 Interface를 엑셀로 정리하기 위해 테이블을 추가하고, 수 천 라인의 소스 코드를 들여다보며 열심히 API 정보를 하나하나 입력해야지..!라고 떠올렸다면 허튼짓을 시작하기 전 문서화 도구를 사용하는 것을 강력하게 추천한다. (필자는 이미 뻘짓을 신나게 끝낸 뒤 깨달았다..😱) 

 

문서화 도구(Documentation Generator)란, 소스 파일에 작성된 주석을 파싱하여 클래스, 메서드 등 API 정보를 HTML 문서로 생성해주는 도구를 지칭한다. 개발 중인 코드에 주석이 잘 작성되어 있다면, 문서화 도구가 제공하는 명령어 한 줄만으로 불필요한 핸드메이드 작업을 피할 수 있다. 자바의 JavaDoc, 파이썬의 Sphinx 등이 문서화 도구에 해당한다. 당연히 자바스크립트를 위한 문서화 도구도 존재한다. 잘 알려진 자바스크립트 문서화 도구로는 JSDoc이 있다.

 

 

 

자바스크립트 API 문서를 작성하기 위함이니 JSDoc이 무엇인지 공부해보았다. 기본적으로 JSDoc는 js 파일 내 주석을 사용하여 코드를 작성하고 인터페이스를 설명하는 문서를 생성할 수 있다.

 

JSDoc 공식 매뉴얼 문서 - @Use JSDoc - jsdoc.app

Use JSDoc: Index

 

 

JSDoc 설치 및 사용법 👀

 

0. 프로젝트 설정

JSDoc을 설정하려는 프로젝트 폴더를 생성하고 터미널을 통해 아래 명령을 수행한다.

// cmd
npm init -y

 

1. JSDoc 설치

package.json, node_modules가 생성된다.

// cmd
npm i -D jsdoc

 

2. 루트 디렉토리에 jsdoc.json 파일 생성

markdown 파일을 읽어 들일 수 있는 plugin을 지정하고, js파일들을 source 파일로 읽어 들인다.

// jsdoc.json
{
    "source": {
        "include": ["src"],
        "includePattern": ".js$",
        "excludePattern": "(node_modules/|docs)"
    },
    "plugins": ["node_modules/jsdoc/plugins/markdown"],
    "templates": {
        "cleverLinks": true,
        "monospaceLinks": true
    },
    "opts": {
        "recurse": true,
        "destination": "./docs/",
    }
}

 

3. 기존 package.json 파일 수정

손쉽게 jsdoc.json 파일을 읽어 들이도록 script 부분을 변경하였다.

// package.json
{
  "name": "MD_JSDoc_Sample",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "doc": "jsdoc -c jsdoc.json"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "jsdoc": "^3.6.6"
  }
}

 

4. 루트 디렉터리에 src/index.js 파일 생성 & doc 명령어 수행

index.html을 포함하는 docs라는 디렉터리가 생성된다. 이로서 기본 환경이 모두 세팅되었다!

// cmd
npm run doc

 

5. index.js에 JSDoc 문법에 맞게 주석 및 코드를 작성한다!

index.js에는 코드들을 API 문서에 파싱 하여 나타내기 위해 주석 부분에 annotation들이 작성되어야 한다.

 

<JSDoc Comment Tags - Document by Microsoft 

@deprecated	@deprecated description	Specifies a deprecated function or method.
@description	@description description	Specifies the description for a function or method.
@param	@param {type} parameterNamedescription	Specifies information for a parameter in a function or method. TypeScript also supports @paramTag.
@property	@property {type} propertyName	Specifies information, including a description, for either a field or member that's defined on an object.
@returns	@returns {type}	Specifies a return value. For TypeScript, use @returnType instead of @returns.
@summary	@summary description	Specifies the description for a function or method (same as @description).
@type	@type {type}	Specifies the type for a constant or a variable.
@typedef	@typedef {type} customTypeName	Specifies a custom type.

 

 - 위 설치 및 환경 구축 방법은 Traversy Media 영상을 참조하여 작성하였습니다.

 

 

(+) template 사용하는 법

생각보다 간단한데 node_module 디렉터리에서 template를 custom 하여 사용하는 과정이 익숙하지 않아 꽤나 헤맸다.😂 [node_modules > jsdoc > templates > default] 폴더를 copy 하여 루트 디렉터리에 paste 한다. custom-template이라고 폴더명을 변경한 뒤 jsdoc.json 파일의 option을 추가한다.

{
    "source": {
        "include": ["src"],
        "includePattern": ".js$",
        "excludePattern": "(node_modules/|docs)"
    },
    "plugins": ["node_modules/jsdoc/plugins/markdown"],
    "templates": {
        "cleverLinks": true,
        "monospaceLinks": true
    },
    "opts": {
        "recurse": true,
        "destination": "./docs/",
        "template": "./custom-template", // custom-template을 사용하기 위해 추가
        "readme": "README.md" // 마크다운 파일을 읽어들이기 위해 추가
    }
}

 

template 폴더 안에 있는 publish.js를 통해 Home 태그에 접근할 수 있다.

 

 

 

 

---

 

초기 환경 세팅만 끝나면 주석 작성은 꽤 간단한 편이다. JSDoc 공식 문서를 통해 충분히 가능하다. 하지만 작업 도중 코드 변경내용을 확인하기 위해 npm run doc을 반복적으로 수행해야 하는 점이 귀찮았다. (hot loader와 같은 확장 플러그인이 있나?) JSDoc을 작성하면서 ts-check문법을 처음으로 접하기도 했다. 조만간 인프런을 통해서 TypeScript를 공부한 뒤 포스팅을 진행해봐야겠다.

 

주니어 개발자로 살아간다는 것은 무엇일까? 복잡한 알고리즘을 통해 그 누구도 떠올리지 못한 예술적인 로직을 짜내고, 거대한 프로그램을 짜 내는 것! 은 너무나도 완벽하지만 현실은 구글링을 통해 수많은 API 문서를 접하고, 기초 지식을 쌓아나가는 과정인 것 같다. 가장 기본적은 API를 작성해보는 과정이 마냥 귀찮지만은 않았다. 가장 필요한 정보를 뽑아내고 그 항목들을 갈무리하면서 역시 기초 지식의 중요성을 다시 한번 깨닫게 되는 계기가 되었다.