코드를 짜다 보면 문서를 따로 만들고 관리하는 것이 여간 귀찮은 것이 아니다.
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