JSDoc 활용하기
Post

JSDoc 활용하기

30/10/2022
2

JSDoc 이란?

Javascript 소스코드 파일에 주석을 달기위해 사용되는 마크업언어이다.

jsdoc

JSDoc의 주요 기능

  • 자동으로 API 문서 생성
  • 타입 정의 및 추론

기본 문법

함수

1
2
3
4
5
6
7
8

/** 
 * 정수의 합산
 * @function add
 * @param {number} a 0 이상의 정수
 * @param {number} b 0 이상의 정수
 * @returns {number} a + b
 */
const add = (a, b) => a + b;

변수

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

/** @type {string} */
let str;

/** @type {number} */
let num;

/** @type {boolean} */
let bool;

/** @type {*} */
let any;

/** @type {?} */
let unknown;

/** @type {number[]} */
let nums;

/** @type { {id: number, content: string, completed: boolean} } */
let obj;

/** @type {string|number} */
let union;

/** @type {Array<{ id: number, content: string, completed: boolean }>} */
let generic;

문서화 하기

  1. jsdoc 설치하기
    1

    npm install -g jsdoc
  2. jsdoc 실행하기
    out 폴더에 api 문서가 생성된다.
    1

    jsdoc ./index.js

폴더 전체 문서화하기

  1. jsdoc.config.json 파일을 루트 경로에 추가
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

    {
 "plugins": [],
 "recurseDepth": 10,
 "source": {
     "includePattern": ".+\\.js(doc|x)?$",
     "excludePattern": "(^|\\/|\\\\)_",
     "exclude": [ "node_modules/" ]
 },
 "sourceType": "module",
 "tags": {
     "allowUnknownTags": true,
     "dictionaries": ["jsdoc","closure"]
 },
 "templates": {
     "cleverLinks": false,
     "monospaceLinks": false
 }
}
  2. 실행하기 src 폴더 아래 모든 파일들이 문서화 된다.
    1

    jsdoc -r -c jsdoc.config.json ./src

메인 화면에 README.md 추가하는 방법

  • jsdoc.config.json 설정
1
2
3
4
5
6
7

    "plugins": [
        "plugins/markdown"
        ],
    "opts": {
        "encoding": "utf8",
        "readme": "README.md"
    }
  • README.md 파일 편집
1
2
3
4

# 나의 문서

## [add](global.html#add)
## [subtraction](global.html#subtraction)
  • 문서를 다시 생성
1

jsdoc -r -c jsdoc.config.json ./src

메인 화면에 README.md 파일의 내용이 보인다.

javascript
javascript jsdoc