Javascript 문서화

주말부터 javascript 패턴에 대한 책도 쉬엄쉬엄 읽고 있는데 거기서 javascript의 문서화에 대한 항목이 나왔다.

나는 가벼운 마음으로 javascript 문서화를 한번 해보기로 마음을 먹었는데 그것이 삽질의 시작이 될거라고는 생각을 못했다.

일단 내가 시도해본 javascript 문서화 도구는 이러하다.

1. YUIDOC

2. JSDOC 또는 여기 

3. GROC ( 이건 차라리 [ 여기서 ] 보고 따라하는게 더 좋다.)

4. ESDOC

결론부터 말하자면 1,2,3,4 전부다 잘 작동한다.

1. YUIDOC는 문법을 많이 따지고 특히 Class구현부터 잘 되어 있는 JS 모듈의 경우에는 잘 작동하지만 Function만 있는 간단한 JS파일에서는 제대로 작동이 안되었다. 그래서 하다가 그냥 멈추었다.

2. JSDOC은 정말 많은 삽질을 했는데 하다하다 왜 안되나 보았더니 '_'로 시작하는 디렉토리를 인식하지 못한다. 예를 들어 디렉토리 이름이 _ABC 라면 기본적으로는 인식할수가 없다. 

[ 관련 내용 : https://github.com/jsdoc3/jsdoc/issues/308 ] 

이것도 모르고 많은 삽질을 하다가 결국 알아내고 _가 없는 디렉토리를 만들어서 해보았더니 잘되었다. 허탈할 정도로..

3. GROC는 마크다운을 활용한 코드로 사용하기가 상당히 쉽지만 구조적인 형태로 보여주지는 못한다. 하지만 사용하기가 편하다.

4. ESDOC는 JSDOC의 ES6버전이라고 생각하면 쉽다. 일단은 ES5를 사용하고 있기 때문에 혹시나 하는 마음으로 써봤는데 ES5에서는 그다지 잘 작동하지 않았다.

위의 Javascript 4가지 문서화 도구는 전부다 NPM으로 쉽게 설치가 된다. 즉 NodeJS를 설치하는게 선행조건이라는 것이다. NodeJS를 설치했다면 아래와 같은 설치과정을 거치면 된다.

GROC 설치방법

1. npm install -g groc

2. JS 파일내에서 주석을 마크다운 주석으로 단다.

3. groc로 그 파일에서 실행시킨다. 예를들어 주석을 ABC.js이라는 파일내에 달아놨다면 groc ABC.js 라고 하면 된다.

이렇게 하면 폴더 또는 HTML파일이 만들어질 것이고 그것을 실행시키면 문서화된 것을 볼수 있다.

JSDOC 설치방법

1. npm install -g jsdoc

2. jsdoc 양식에 맞게 원하는 javascript 파일에 주석을 단다.

3. jsdoc 원하는 javascript 파일을 실행시킨다. js 폴더 안에 ABC.js에 달았다면,   jsdoc  ./js/ABC.js  이렇게 파이핑을 친다.

4. 이렇게 하면 자동으로 out 폴더가 생기고 그 안에 여러 파일이 생성된 것을 볼수 있다. 그중 index.html을 클릭해서 보면 된다.

원래 다 포기하고 GROC쓸려고 했는데 오늘 아침 다행히 언더바 _ 문제를 알게 되어서 JSDOC로 문서화를 할수 있게 되었다. 이제 문서화도 했으니까 다음에는 MOCA, Jasmine을 이용한 테스팅도 시도해봐야 겠다.