JSDoc 설치 및 사용방법 | JavaDoc과 비슷한 JSDoc으로 자바스크립트 문서화
목차
JavaScript에서 JAVADOC 처럼 문서를 뽑아주는 JSDOC 이라는 플러그인이 있습니다. 이에 대해 구체적인 사용방법이 정리되어 있는 블로그가 없는 것 같아 정리해 봅니다. ESDOC 설치 관련해서는 다음의 포스팅을 참조해주세요.
ESDoc 설치 및 사용방법 | ES6 자바스크립트 문서화하기
목차 esdoc은 JavaScript용 문서 제네레이터, 특히 es6에 특화된 documentation generator입니다. 비슷하게 JavaScript의 주석을 문서로 만들어주는 것으로, JSdoc 도 있습니다. 현재 진행하고 있는 프로젝트는 es6
pliss.tistory.com
JSDOC은 다양한 템플릿으로 문서를 만들 수 있습니다. 저는 docdash라는 테마가 자주 사용된다고 하여 이것 또한 설치하여 사용할 겁니다. 최종 완성된 모습은 다음과 같은 형태를 띄게 됩니다.
설치 및 사용방법
설치 및 사용 방법입니다.
1. npm으로 jsdoc 설치
먼저 터미널을 열고, > npm install jsdoc
2. docdash 테마 설치
jsdoc 이 설치된 폴더로 이동하여, > npm install docdash
3. jsdoc으로 javascript 파일 문서화
보통 document를 만들 때, 하나의 파일만 문서화하지 않습니다. 그러나 예제로, 하나의 JavaScript 파일만 문서화 해보겠습니다. 먼저 javadoc 처럼 문서를 뽑아내기 위해서 주석과 규칙을 이용해서 자바스크립트 파일에 문서를 추가해야겠죠? 이 과정은 좀 더 아래에서 나중에 설명하겠습니다.
4.
3의 과정에서 자바스크립트 파일에 jsdoc을 이용해 문서화하기 위한 것들을 작성하고 나면, javascript 파일이 있는 경로로 이동하여 > jsdoc [javascript] -t [docdash 경로] 명령어를 이용해 문서화합니다. -t 는 템플릿을 사용하겠다는 것입니다. docdash 경로는 jsdoc이 설치되어 있는 경로내에 존재합니다. 아래 그림 예제를 참고하세요.
5. jsdoc 문서화 확인
jsdoc을 실행한 해당 경로에 out 폴더가 생겼을 겁니다. 여기서 index.html 을 열어보면 다음과 같이 html 문서를 확인할 수 있습니다.
6. Readmd.md 작성하기
문서를 만들고 나면, 문서의 HOME 페이지가 허전할 겁니다. 이 부분은 마크다운 문서인 README.md 를 작성하여 채워넣습니다.
> jsdoc [javascript 파일] [markdown 파일]
아래는 예입니다.
7. 여러개 한번에 문서화하기
아까 말씀드렸듯, 보통 하나의 파일만을 문서화하지 않죠. 폴더 내의 모든 javascript 파일을 한 번에 문서화할 수도 있습니다.
> jsdoc [폴더] -r
8. 최종 정리
README.md 파일을 HOME 으로 사용하고, 동시에 폴더 내 모든 자바스크립트 파일을 문서화하며, 이 때 docdash 템플릿까지 이용하는 방법은 다음과 같습니다.
> jsdoc [폴더] [markdown 파일] -r -t [docdash 경로]
지금까지 jsdoc 이용방법을 알아보았습니다. 물론 config 설정 등 더 간편한 방법들도 있습니다. 그럼 방법 4에서 언급드렸듯, 이제는 jsdoc 문서를 뽑기 위한 규칙들을 살펴보겠습니다.
