Javascript Documentation 라이브러리 JSDoc를 사용해 봅시다

📌 연관 글

1. Javascript Documentation 라이브러리 JSDoc를 사용해 봅시다
2. JSDoc을 설정 파일로 빼서 사용해보도록 합시다
3. JSDoc에서 템플릿을 사용해 보도록 합시다
4. Webpack과 JSDoc을 연동하여 자동화를 시켜봅시다

---

여러분들은 Javascript에서 Documentation을 어떻게 관리하고 계시나요?

가장 좋은 방법은 소스코드만 봐도 저절로 읽히는 코드가 가장 좋은 코드이지만,

그렇지 못한 경우이거나 간단한 개발 같은 경우는 주석으로 어떠한 역할을 하는 코드인지 써놓습니다.

하지만 이러한 주석들은 직접 찾아야 하는 번거로움도 있으며,

코드가 인수인계 시 한눈에 확 들어오지 않는 경우도 많이 있습니다.

이러한 문제를 해결하기 위한 라이브러리!! 오늘은 JSDoc에 대해서 알아보도록 하겠습니다.

 

JSDoc 소개

 

---

JSDoc이란?

JSDoc는 구조화된 블록 주석을 기반으로 Web Documentation을 만들어주는 라이브러리입니다.

일단 말 만들어서는 잘 모르시겠죠? 한번 사진으로 확인해 보도록 하겠습니다.

JSDoc Documentation

엄청 미려하지 않나요?

사실 JSDoc는 다양한 템플릿을 가지고 있어서 사용자의 입맛에 따라 다양한 템플릿을 사용할 수 있습니다.

JSDoc - Github에서도 템플릿들을 지원하고 있습니다. 

 

JSDoc에서 공식적으로 지원하는 Templet들

사설이 좀 길었습니다. 그럼 이제 사용하는 방법을 알아보도록 할까요?

 

프로젝트 환경설정

 

일단 기본적으로 JSDoc는 npm을 사용합니다.

그렇기 때문에 npm을 설치해놓았다는 전제하에 작업을 진행하도록 하겠습니다.

(=> 저는 Windows 10을 사용하고 있기 때문에 Windows 10 기반으로 작업을 진행합니다.)

 

그럼 명령 프롬프트를 실행시켜 원하는 프로젝트 폴더로 이동 후 아래와 같이 입력하도록 합니다.

$ mkdir jsdoc-test
$ cd jsdoc-test
$ npm init -y
$ echo $null >> index.js

 

그럼 해당 프로젝트 폴더에 package.json과 index.js가 생성된 것을 볼 수 있습니다.

그럼 JSDoc를 설치해보도록 하겠습니다.

 

JSDoc 설치 및 실행

해당 프로젝트 루트 디렉토리에서 아래와 같은 명령어를 입력합니다.

어차피 개발용으로만 사용할 것이므로 -D 옵션을 넣어줍니다.

$ npm i -D jsdoc

 

저는 현재 기준 jsdoc@3.6.3을 설치했습니다. 

 

자 그럼 node_module 폴더가 생긴 게 보이실 겁니다.

그럼 이제 JSDoc을 실행시켜보도록 하겠습니다.

저희가 루트 디렉토리에 만들었던 index.js 파일에 아래와 같은 소스를 붙여넣어 봅시다.

/**
 * "Hello {이름}"을 반환하는 메소드
 *
 * @param {string} name 사용자가 반환하길 원하는 이름을 출력합니다.
 * @returns {string} Hello + name
 */
function hello(name) {
  return "Hello " + name + "!";
}

 그 후 루트 디렉토리 터미널에서 아래와 같은 커맨드를 입력해 줍니다.

$ ./node_modules/.bin/jsdoc ./index.js

그럼 아래의 사진과 같이 out이라는 디렉토리가 나오게 됩니다. 

이 out 디렉토리가 JSDoc이 만드는 Documentation입니다.

그럼 한번 열어보도록 할까요?

아래 네모 박스가 쳐진 index.html을 열어보도록 합니다.

위와 같이 웹에서 Documentatino이 자동으로 생성되는 것을 확인할 수 있습니다.

어때요, 굉장히 쉽죠?

 

마치며

이것으로 전체적인 JSDoc의 설치방법과 기본적인 실행방법에 대해 알아볼 수 있었습니다.

하지만 이것으로 끝나면 굉장히 번거롭게 Documentation을 만들게 되어 좀 아쉽습니다.

걱정 마세요~!!

이 JSDoc 시리즈는 앞으로 3번에 포스팅에서 템플릿 적용 방법과 자동화를 적용하는 방법을 다뤄볼 것입니다.

그럼 다음 글에서 뵙도록 하겠습니다 😀