[Front end] JavaScript JSdoc 설치 및 설정

JSdoc을 사용하여 자바스크립트를 문서화하는 도구이다. 간단한 설정과 명령어로 주석을 통해 깔끔한 템플릿을 통해 문서를 만들어준다. frontend 에도 주석을 꼼꼼히 다는 습관이 필요하다.

https://github.com/jsdoc/jsdoc

jsdoc/jsdoc

https://github.com/clenemt/docdash

clenemt/docdash

 

설치 및 설정

npm 또는 yarn을 통해 jdsoc과 템플릿 docdash 모듈 설치가 필요하다.

yarn add jsdoc
yarn add docdash

설치가 완료되면 jsdoc.conf 파일을 만들어 보자. 파일 생성 위치는 프로젝트 루트이다.

{
  "tags": {
    "allowUnknownTags": false
  },
  "source": {
    "include": ["./src"], // 읽을 파일명, 디렉토리명 배열
    "includePattern": ".js$", // 파일의 패턴
    "exclude": ["./docs"], // 제외할 파일명, 디렉토리명 배열
    "excludePattern": "(node_modules/|docs)" // 제외할 파일의 패턴
  },
  "plugins": [
    "plugins/markdown"
  ],
  "opts": {
    "template": "node_modules/docdash", // 템플릿 경로
    "encoding": "utf8",
    "destination": "./docs", // 문서를 만들 경로
    "recurse": true,
    "verbose": true
  },
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false,
    "default": {
      "outputSourceFiles": false
    }
  },
  "docdash": { // docdash 템플릿 옵션
    "static": false,
    "sort": true
  }
}

또한 yarn 명령어를 통해 실행할 수 있게 package.json을 수정해보자.

...
"scripts": {
    "start": "cross-env NODE_ENV=production NODE_PATH=src react-scripts start",
    "build": "cross-env NODE_PATH=src react-scripts build",
    "test": "react-scripts test --env=jsdom",
    "eject": "react-scripts eject",
    "jsdoc": "jsdoc -c jsdoc.conf"
  },
  ...

package.json에서 scripts 구문에 "jsdoc" : "jsdoc -c jsdoc.conf"를 추가하면 된다. 이로써 아래와 같은 명령어로 간단하게 문서화가 가능하게 되었다.

yarn jsdoc

 

주석 예시

/** Class representing a point. */
class Point {
    /**
     * Create a point.
     * @param {number} x - The x value.
     * @param {number} y - The y value.
     */
    constructor(x, y) {
        // ...
    }

    /**
     * Get the x value.
     * @return {number} The x value.
     */
    getX() {
        // ...
    }

    /**
     * Get the y value.
     * @return {number} The y value.
     */
    getY() {
        // ...
    }

    /**
     * Convert a string containing two comma-separated numbers into a point.
     * @param {string} str - The string containing two comma-separated numbers.
     * @return {Point} A Point object.
     */
    static fromString(str) {
        // ...
    }
}