JSDoc 사용해 JavaScript 파일 문서화하기 (+Github Pages 배포)

JSDoc 이란?

JavaScript의 JavaDoc와 유사한 JavaScript용 API 문서화 툴이다. 문서 주석을 코드와 함께 소스코드에 직접 추가할 수 있고, JSDoc은 소스 코드를 스캔하고 HTML 문서를 생성한다. 각 주석은 /** 시퀀스로 시작해야 JSDoc 파서가 인식할 수 있다.
또 JSDoc에서 제공하는 태그를 이용해서 클래스, 함수, 모듈, 메서드, 파라미터 등을 문서화한다. 여러 종류의 태그들이 있어서 잘 사용하면 구체적인 정보가 담긴 문서를 만들 수 있다.

초기환경 세팅/설치

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

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

# 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에 아래의 예시를 옮겨 적어보자

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

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

jsdoc ./src/index.js

out/index.html을 우클릭해서 브라우저에서 연 후, add를 누르면 문서화된 JSDoc을 볼 수 있다.

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

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

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

예시를 들기 위해 이번에는 뺄셈에 관한 함수를 만들어보자.

/** 
 * a는 b보다 크거나 같다
 * a가 b보다 적은 수라면 -1을 반환한다
 * @function subtraction
 * @param {number} a 연산하고자 하는 0 이상의 정수
 * @param {number} b 연산하고자 하는 0 이상의 정수
 * @returns {number} a - b
 */

const subtraction = (a, b) => a >= b ? a - b : -1;

이제 src 폴더에는 덧셈에 대한 함수를 포함한 index.js와 뺄셈에 대한 함수를 포함한 test.js가 있다.

여기서 두 js 파일들을 모두 합쳐 하나의 JSDoc 문서로 만들기 위해서는 아래의 코드를 치면 된다.

이 경우는, 경로를 직접 입력해야 모든 문서가 합쳐진 하나의 문서로 만들어진다.

jsdoc ./src/index.js ./src/test.js

그럼 다음과 같이 index.html을 새로고침했을 때 다음과 같이 두 개의 함수가 함께 뜨는 것을 볼 수 있다.

그치만 이 방법은 너무 번거롭고 비효율적이므로 폴더 내부의 모든 js, jsx, jsdoc 확장자를 가진 파일이

한꺼번에 동작할 수 있도록 설정 파일을 수정해보자.

루트 위치에 jsdoc.config.json 이라는 이름을 가진 파일을 하나 생성한다.

그리고 위에서 언급한 확장자를 가진 파일을 모두 문서로 만들어주는 객체를 만들어주자.

jsdoc.json 기본 설정

source 객체 내부에 "include": ["폴더명"]을 추가해준다.

배열이기 때문에 루트 위치와 특정 폴더 위치를 모두 삽입해주면 아래와 같이 구성된다.

"source": {
	"include": [".", "src"],
  },

또 아래에서 다루겠지만 JSDoc이 md 파일도 인식할 수 있게 해야하므로 다음 코드도 추가해줘야한다.

"plugins": [
  "plugins/markdown"
],

"opts": {
  "readme": "README.md"
}

그럼 최종 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"
	}
}

설정 값을 수정하고 다시 아래의 코드를 통해 문서를 만들면 의도했던 대로 모든 .js 파일을 문서로 확인할 수 있다.

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

README.md 추가하기

문서화는 완료됐는데 문서로 진입하기 전 메인화면이 너무 텅 비어있으니,

여기에 README.md를 추가해서 문서에 관한 간단한 설명을 작성해보자.

루트위치에 README.md를 생성하고 다음과 같이 작성한다.

# 사칙연산 문서

## [addition](global.html#addition)

## [subtraction](global.html#subtraction)

## [multiplication](global.html#multiplication)

설정값을 변경 후 문서를 닷 만들면 아래와 같이 메인화면이 변경된다.

링크를 클릭하면 해당 함수의 설명 위치로 가는 README.md 파일이 생성되었다!

여기서 매번 ./node_modules/.bin/jsdoc -c jsdoc.json . 명령어를 이용하여 문서화를 했다.

좀 더 간단한 명령어를 사용할 수는 없을까?

Webpack을 사용하면 이런 문제를 해결할 수 있다.

Webpack과 jsdoc-webpack-plugin 설치

npm i -d webpack webpack-cli jsdoc-webpack-plugin

설치가 완료되었으면 루트 위치에 webpack.config.js 파일을 생성해 webpack에 대한 설정을 한다.

const path = require("path");
const JsDocPlugin = require("jsdoc-webpack-plugin");

module.exports = {
  entry: "./src/index.js",
  output: {
    path: path.join(__dirname, "dist"),
    filename: "main.js"
  },
  plugins: [
    new JsDocPlugin({
      conf: "jsdoc.json",
      cwd: ".",
      preserveTmpFile: false
    })
  ]
};

그리고 package.json 파일에서 start 명령어를 추가해준다.

"scripts": {
    "start": "webpack"
  },

이제 npm start라고 명령어를 입력하면 문서화 작업을 진행할 수 있다!

JSDoc을 Github Pages로 배포하기

API는 결국 공유가 필요한 문서이므로, 쉽게 고유하려면 JSDoc를 배포하면 된다.

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

(가장 기본적이지만, 깃헙 페이지로 배포하기 위해서는 위에서 만든 jsdoc-practice 파일이 레포에 최종 push 되어있어야 한다.)

gh-pages 설치

npm install --save gh-pages

package.json 수정

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

배포하기

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

npm run deploy

그 다음 Github의 해당 레포의 Settings->Pages 탭으로 이동하여

Source는 Deploy from a branch 로 선택해주고, Branch는 gh-pages로 설정한다.

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

king yejin's smartfarm