JSDoc?

코드를 짜다 보면 문서를 따로 만들고 관리하는 것이 여간 귀찮은 것이 아니다.

JSDoc은 자바스크립트로 프로그래밍을 할 때 주석을 열심히 달면 자동으로 이쁜 문서를 만들어 주는 훌륭한 문서화 도구이다.

문서도 만들고 주석을 꼼꼼하게 다는 습관도 기를 수 있다.

 

설치하기

npm으로 jsdoc과 마음에 드는 템플릿을 프로젝트에 추가시킨다.

 

나는 docdash 템플릿이 마음에 들어서 docdash도 같이 추가시켰다.

npm install --save jsdoc docdash

 

jsdoc은 여러가지 옵션이 있으며 inline command로 설정할 수도 있지만 설정할 것이 많기 때문에 별도의 설정파일을 만들겠다.

 

jsdoc.json을 프로젝트 루트 경로에 만든다.

{
  "tags": {
    "allowUnknownTags": false
  },
  "source": {
    "include": ["YOUR SOURCE PATH"], // 주석을 읽을 파일명이나 디렉토리명 배열
    "includePattern": ".js$", // 읽을 파일의 패턴
    "exclude": ["./docs"], // 제외할 파일명이나 디렉토리명 배열
    "excludePattern": "(node_modules/|docs)" // 제외할 파일의 패턴
  },
  "plugins": [
    "plugins/markdown"
  ],
  "opts": {
    "template": "node_modules/docdash", // 다운받은 템플릿 경로
    "encoding": "utf8",
    "destination": "YOUR DOCUMENT OUTPUT PATH", // 문서를 만들 경로
    "recurse": true,
    "verbose": true
  },
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false,
    "default": {
      "outputSourceFiles": false
    }
  },
  "docdash": { // docdash 템플릿에서 지원하는 옵션
    "static": false,
    "sort": false
  }
}

 

주석 달기

프로젝트 루트 경로에 src 폴더를 하나 만들고 그 안에 app.js파일을 만든다.

그리고 나서 jsdoc.json 파일의 include를 ["./src"]로 설정해준다.

 

your_project/src/app.js에 간단한 코드를 만들고 JSDoc 양식으로 주석을 달아본다.

/**
 * App 클래스 입니다.
 * @class
 */
var App = function () {

    /**
     * message를 입력받아 출력하는 함수입니다.
     * @param message {string} 출력할 메세지 입니다.
     */
    var printMessage = function(message) {
        console.log(message);
    }

};

 

문서 만들기

커맨드라인에 jsdoc 명령어를 실행한다.

jsdoc -c jsdoc.json