이미지 출처: https://www.reddit.com/r/programming/comments/nllcvt/typecheck_your_javascript_with_jsdoc/

JSDoc

JavaScript의 API를 문서화하는 툴이다. JSDoc에서 제공하는 태그를 이용해서 클래스, 함수, 모듈, 메서드, 파라미터 등을 문서화한다. 여러 종류의 태그들이 있어서 잘 사용하면 구체적인 정보가 담긴 문서를 만들 수 있다.

JSDoc의 태그 종류

jsdoc.app

JSDoc 3.6 한국어

📌 JSDoc 사용 방법

주석을 코드와 함께 소스코드에 작성하면, JSDoc이 소스코드를 기반으로 HTML 문서를 생성한다.

주석을 작성할 때 /** 주석 */ 와 같이 입력하면 JSDoc이 인식할 수 있는 주석이 된다.

작성하는 주석의 예시는 아래와 같다.

/** 
 * 두 개의 숫자를 받아서 합한 값을 리턴하는 add 함수
 * @param {number} number1 - 첫 번째 숫자
 * @param {number} number2 - 두 번째 숫자
 * @returns {number} number1 + number2
 */
function add(number1, number2) {
	return number1 + number2;
}

초기 환경 세팅 / 설치

원하는 디렉토리에 JSDoc을 만들 새 폴더 생성

# jsdoc-practice 폴더 생성, 진입
mkdir jsdoc-practice
cd jsdoc-practice

# package.json 생성
npm init -y

# src 폴더 생성, 진입
mkdir src
cd src

# index.js 파일 생성
touch index.js

# jsdoc 설치 (전역으로 설치하면 명령어가 간단하다)
npm install -d jsdoc
npm install -g jsdoc

JSDoc 주석 작성

생성한 index.js에 위의 예시를 옮겨 적어보자.

JSDoc을 사용하면 타입 체킹 도 가능하다.

터미널에 아래와 같이 jsdoc으로 변환해주는 명령어를 입력하면 디렉토리에 out 폴더가 생성된다.

jsdoc ./src/index.js

out/index.html 을 오른쪽 클릭해서 브라우저에서 열어보면 문서화된 JSDoc을 볼 수 있다.

중간 쯤에 있는 파란색 index.js 링크를 클릭하면 작성한 소스코드도 확인할 수 있다.

📌 여러개의 .js 파일을 합쳐서 하나의 JSDoc 문서 만들기

보통 src 폴더 내에 여러개의 .js 파일들이 있다.

이 모든 파일들이 합쳐진 JSDoc을 만들기 위해서는 아래와 같이 jsdoc.config.json 파일을 만든다.

jsdoc.config.json

root 디렉토리에 jsdoc.config.json 파일을 만들고, 아래와 같이 기본 설정을 한다.

{
	"plugins": ["plugins/markdown"],
	"recurseDepth": 10,
	"source": {
		"include": [".", "src"],
		"includePattern": ".+\\.js(doc|x)?$",
		"excludePattern": "(^|\\/|\\\\)_"
	},
	"sourceType": "module",
	"tags": {
		"allowUnknownTags": true,
		"dictionaries": ["jsdoc", "closure"]
	},
	"templates": {
		"cleverLinks": false,
		"monospaceLinks": false
	},
	"opts": {
		"encoding": "utf8",
		"readme": "README.md"
	}
}

아래 명령어를 입력하면 하나로 합쳐진 JSDoc 문서를 볼 수 있다. (JSDoc 브라우저를 다시 열거나 새로고침)

./node_modules/.bin/jsdoc -c jsdoc.config.json .

JSDoc에 README.md 추가하기

JSDoc의 Home이 비어있다.

여기에 README.md 파일을 넣을 수 있다.

이 문서를 소개하는 내용을 담아 README.md 파일을 작성해서 Home에서 보여주면 좋지 않을까?

README.md

root 디렉토리에 README.md 파일을 생성하고 내용을 입력한다.

# JSDoc 문서 제목

## 💁🏻‍♀️ 문서 소개

JSDoc 작성하는 방법을 연습해보는 문서입니다.
잘 작성해 봅시다! ✨

저장 후 다시 아래 명령어를 입력해서 문서를 만들면 README.md 가 반영된 JSDoc 을 확인할 수 있다.

./node_modules/.bin/jsdoc -c jsdoc.config.json .

📌 JSDoc을 Github Pages 로 배포하기

너무나도 당연한 이야기지만 API 문서는 공유가 필요한 문서다.

쉽게 공유하려면 JSDoc을 배포하면 된다.

만든 JSDoc 정적 페이지를 Github Pages로 배포해보자.

(역시 당연한 이야기지만, Github Pages 로 배포하기 위해서는 위에서 만든 jsdoc-practice 파일이 Github 레포지토리에 최종 push 되어있어야 한다.)

gh-pages 설치

먼저 gh-pages 패키지를 설치한다.

npm install --save gh-pages

package.json 수정

package.json 파일을 내부에 homepage를 아래와 같이 추가해서 수정한다.

// "homepage": "https://깃헙아이디.github.io/레포지토리이름"
"homepage": "https://ekim49.github.io/wanted-pre-onboarding-challenge-fe-ts"

package.json 파일 내부의 scripts 를 수정한다.

"scripts": {
	"docs": "jsdoc -c jsdoc.json",
	"predeploy": "npm run docs",
	"deploy": "gh-pages -d docs"
}

배포하기

script 수정 후 터미널에 아래 명령어를 입력해서 배포한다.

npm run deploy

그 다음 Github의 해당 레포지토리의 Settings → Pages 탭으로 이동한다.

Source 를 Deploy from a branch 로 선택하고,

Branch 는 gh-pages 로 설정한다.

그리고 위의 visit site 버튼을 클릭하거나, 링크를 클릭하면 배포된 JSDoc 을 확인할 수 있다. 👏🏼👏🏼👏🏼

🎨 docdash: JSDoc 템플릿 사용하기

docdash 설치

JSDoc에 다양한 템플릿이 있는데, 그 중 docdash 가 많이 쓰인다고 한다.

docdash 를 사용하면 JSDoc의 가독성을 조금 더 높일 수 있다. (+ 심미적인 만족감)

npm install docdash

jsdoc.config.json 수정

jsdoc.config.json 을 수정한다.

"opts": {
	"template": "node_modules/docdash",
	...
}

다시 아래 명령어를 입력해서 JSDoc을 생성하면 아래와 같은 템플릿이 적용된다.

./node_modules/.bin/jsdoc -c jsdoc.config.json .

훨씬 읽기가 좋아졌다! 👍

혹시나 잘못된 정보가 있다면 댓글로 알려주시면 찾아보고 반영하겠습니다. 감사합니다 ☺️

References

jsdoc.app

JSDoc 3.6 (한국어)

jsdoc-boilerplate

JSDoc을 사용해 JavaScript 파일 문서화하기