JSDoc을 사용하여 JavaScript 코드를 문서화하는 방법

소프트웨어 개발 과정에서 코드 문서화는 매우 중요한 요소이지만, 종종 간과되는 경향이 있습니다. 개발자들은 효율적이고 깔끔한 코드를 작성하는 데 익숙하지만, 효과적인 문서를 만드는 데는 상대적으로 경험이 부족할 수 있습니다.

잘 작성된 문서는 팀원뿐만 아니라, 나중에 코드를 다시 봐야 하는 자신에게도 매우 유용합니다. 특정 방식으로 코드를 구현한 이유나 특정 기능 혹은 API 사용법에 대한 명확한 설명을 제공합니다.

JavaScript 개발자에게 JSDoc은 코드 문서화를 시작하기에 훌륭한 도구입니다.

JSDoc이란 무엇인가?

코드 문서화는 복잡하고 지루한 작업으로 여겨질 수 있습니다. 하지만 "코드가 곧 문서다"라는 접근 방식의 중요성이 점차 강조되면서, 많은 언어에서 문서 자동화를 지원하는 라이브러리가 개발되었습니다. JavaScript에서도 Go 언어의 GoDoc처럼 JSDoc이 이러한 역할을 수행합니다.

JSDoc은 JavaScript 소스 코드에 삽입된 특수 주석을 해석하여 문서를 생성합니다. 이 주석들을 분석하여 맞춤형 문서를 만들고, HTML 형식으로 제공하여 쉽게 접근할 수 있도록 합니다.

이 방식을 사용하면 문서가 코드 내에 유지되므로 코드가 변경될 때마다 문서를 쉽게 업데이트할 수 있다는 장점이 있습니다.

JSDoc 설정

JSDoc 개발자들은 JavaScript 프로젝트에서 JSDoc을 쉽게 설치하고 사용할 수 있도록 설계했습니다.

JSDoc을 프로젝트에 로컬로 설치하려면 다음 명령어를 실행하세요.

npm install --save-dev jsdoc

이 명령어는 JSDoc 라이브러리를 개발 의존성으로 프로젝트에 추가합니다.

JSDoc을 사용하기 위해서는 소스 코드 내에 특별한 구문 주석을 사용해야 합니다. 모든 문서 주석은 `/**`와 `*/` 마커 사이에 작성합니다. 이 주석 안에는 정의된 변수, 함수, 함수 매개변수 등을 상세히 설명할 수 있습니다.

예를 들어 다음과 같습니다:

* 사용자 이름을 기준으로 사용자 정보를 가져옵니다.
* @param {string} name - 사용자 이름
* @returns {string} 사용자 정보
*/
function getUser(name) {
  const User = name;
  return User;
}

@param과 @returns 태그는 JSDoc이 코드 설명을 위해 지원하는 다양한 특수 키워드 중 일부입니다.

이 코드에 대한 문서를 생성하려면 `npx jsdoc` 명령어와 함께 JavaScript 파일 경로를 입력하여 실행하세요.

예시:

npx jsdoc src/main.js

JSDoc을 전역적으로 설치한 경우에는 `npx` 플래그를 생략하고 아래 명령어를 실행할 수 있습니다.

이 명령어는 프로젝트 루트 디렉토리에 `out` 폴더를 생성합니다. 이 폴더 안에는 문서 페이지를 나타내는 HTML 파일들이 들어 있습니다.

로컬 웹 서버를 설정하여 문서를 호스팅하거나, 브라우저에서 `out/index.html` 파일을 열어서 확인할 수 있습니다. 다음은 기본 문서 페이지의 예시입니다.

JSDoc 출력 구성

구성 파일을 생성하여 JSDoc의 기본 동작을 변경할 수 있습니다.

이를 위해 `conf.js` 파일을 만들고, JavaScript 모듈을 내보내세요.

예시:

module.exports = {
  source: {
    includePattern: ".+\\.js(doc|x)?$",
    excludePattern: ["node_modules"],
  },
  recurseDepth: 5,
  sourceType: "module",
  opts: {
    template: "path/to/template",
    destination: "./docs/",
    recurse: true,
  },
};

구성 파일 내부에는 다양한 JSDoc 설정 옵션이 존재합니다. 템플릿 옵션을 사용하면 문서의 모양을 원하는 대로 사용자 정의할 수 있으며, JSDoc 커뮤니티에서는 다양한 템플릿을 제공하고 있습니다. 또한, 사용자 정의 템플릿을 만들 수도 있습니다.

생성된 문서의 위치를 변경하려면 `destination` 구성 옵션을 원하는 디렉토리로 설정하세요. 위의 예시에서는 프로젝트 루트에 있는 `docs` 폴더를 지정합니다.

구성 파일을 사용하여 JSDoc을 실행하려면 다음 명령어를 사용하세요.

jsdoc -c /path/to/conf.js

이 명령어를 더 쉽게 실행하기 위해 `package.json` 파일 내의 스크립트 항목에 추가할 수 있습니다.

"scripts": {
    "dev": "nodemon app.js",
    "run-docs": "jsdoc -c /path/to/conf.js"
  },

이제 터미널에서 npm 스크립트 명령어를 실행하여 JSDoc을 편리하게 사용할 수 있습니다.

JSDoc으로 생성된 문서 예시

다음은 덧셈과 뺄셈 메소드를 포함하는 간단한 산술 라이브러리입니다.

잘 문서화된 JavaScript 코드의 예시입니다:

* 기본적인 산술 연산을 수행하는 라이브러리입니다.
* @module arithmetic
*/
module.exports = {
  
    
    * 두 숫자를 더합니다.
    * @param {number} a - 첫 번째 숫자.
    * @param {number} b - 두 번째 숫자.
    * @return {number} 두 숫자의 합.
    * @throws {TypeError} 인수가 숫자가 아닐 경우 발생합니다.
    *
    * @example
    * const arithmetic = require('arithmetic');
    * const sum = arithmetic.add(5, 10);
    * console.log(sum);
    */
    add: function(a, b) {
        if (typeof a !== 'number' || typeof b !== 'number') {
            throw new TypeError('인수는 모두 숫자여야 합니다.');
        }
        return a + b;
    },

    
    * 첫 번째 숫자에서 두 번째 숫자를 뺍니다.
    * @param {number} a - 빼는 기준 숫자.
    * @param {number} b - 빼는 숫자.
    * @return {number} 뺄셈 결과.
    * @throws {TypeError} 인수가 숫자가 아닐 경우 발생합니다.
    *
    * @example
    * const arithmetic = require('arithmetic');
    * const difference = arithmetic.subtract(10, 5);
    * console.log(difference);
    */
    subtract: function(a, b) {
        if (typeof a !== 'number' || typeof b !== 'number') {
            throw new TypeError('인수는 모두 숫자여야 합니다.');
        }
        return a - b;
    }

};

JSDoc 주석은 라이브러리와 해당 메소드에 대한 명확하고 포괄적인 설명을 제공합니다:

라이브러리와 그 목적에 대한 설명
각 메소드의 매개변수 (타입 및 간략한 설명 포함)
각 메소드가 반환하는 값과 타입
각 메소드에서 발생할 수 있는 오류와 조건
각 메소드 사용 방법 예시

또한, 주석에는 이 파일이 모듈임을 나타내는 `@module` 태그와 각 메소드에 대한 코드 예시를 제공하는 `@example` 태그가 포함되어 있습니다.

개발자 코드를 올바르게 문서화하기

JSDoc은 JavaScript 코드 문서화를 시작하는 데 매우 유용한 도구입니다. 간편한 통합을 통해 코드를 작성하는 동시에 빠르고 상세한 문서를 생성할 수 있습니다. 또한, 작업 환경 내에서 바로 문서를 유지하고 업데이트할 수 있습니다.

하지만 JSDoc의 자동화 기능은 매우 유용하지만, 고품질의 문서를 생성하기 위해서는 몇 가지 지침을 따라야 합니다.