Sencha JSDuck을 이용한 자바스크립트 API 문서 생성법입니다.

1. JSDuck을 이용한
Javascript API 문서 생성
by Forrest

2. 목차
• JSDuck Download
• 테스트
• 자주 사용하는 옵션
• 자주 사용하는 어노테이션

3. JSDuck Download
• jsduck home : https://github.com/senchalabs/jsduck
• 홈페이지 중간 정도에서 “Windows binary”를 클릭

4. • jsduck-xxx.exe 파일을 다운로드한다.
• 이 파일은 설치파일이 아니라 실행파일이다.
JSDuck Download

5. 테스트
• test.js

6. 테스트
• 주석은 자바 주석과 같다.
/** */ : API 문서 주석을 의미한다. 다음에 올 객체, 메소드나 속성을 설명한다.
6 라인 : 메소드를 설명한다. (생략가능)
7-9 라인 : API에 출력할 어노테이션을 적어준다.
※ 어노테이션은 jsduck에서 기술한 어노테이션을 적어준다. 그렇지 않으면 Warning을 출
력하거나 API 문서화에 실패할 수 있다.

7. 테스트
• 관리자 모드로 cmd 실행
c:~>jsduck-6.0.0-beta.exe test.js --output docs
- jsduck 실행파일과 test.js 파일은 같은 폴더 안에 있던가, 아니면 test.js의 전체경로를 적
어줘야 한다.
- --output : 출력할 폴더를 적어준다. 필수 옵션이다.
- 정상적으로 문서가 생성되면 아무 메시지 없이 종료된다.
- 폴더를 살펴보면 docs 폴더가 생성된 것을 확인할 수 있다.

8. 테스트
• 생성된 docs 폴더에 index.html을 실행해 보면 문서가 생성된 것을 확인 할 수 있다.

9. 테스트

10. 자주 사용하는 옵션
• --config=<json파일> : jsduck을 설정파일을 이용해 실행한다.
Ex) jsduck-xxx.exe --config docs-config.json --output docs
- config파일은 json형식으로 작성한다.
{
"--title": "My personal docs", // 문서의 제목
"--welcome": "welcome.html", // API를 열었을 때 가장 처음 보여줄 페이지
“--warnings＂: [＂-link＂, ＂-no_doc＂], // -link: link가 없는 경우 warnin을 출력한다.
–no_doc: 문서가 없는 경우 warning을 출력한다.
"--seo": true, // 검색엔진에 최적화된 상태로 문서 생성
＂—＂: [
"src/Foo.js", // 문서화 할 js 파일 목록
"src/Bar.js", // 폴더 전체를 문서화 할 경우 폴더 경로까지만 적어준다.
"src/Baz.js"
]
}

11. 설정 파일
• config.json
• c:>jsduck-xxx.exe --config docs-config.json --output docs

12. 자주 사용하는 옵션
• --output=<디렉토리>: 생성된 문서를 저장할 디렉토리를 지정한다.(필수 옵션)
예) jsduck-xxx.exe –config docs-config.json –output docs
• --encoding=<NAME>: 문서 인코딩을 설정한다.
예) jsduck-xxx.exe --config docs-config.json --output docs --encoding=utf-8
• --warning=<옵션> : 문서 작업 시에 warning에 지정된 옵션만 warning으로 출력한다.
예1) jsduck-xxx.exe --config docs-config.json --output docs
--warnings=-no_doc,-no_doc_member,-type_name
예2) jsduck-xxx.exe --config docs-config.json --output docs
--warnings=-no_doc:extjs/src
--warnings=-no_doc_member:extjs/src
--warnings=-link:extjs/src
--warnings=-type_name:extjs/src
※ 자세한 warning 옵션은,
C:> jsduck-xxx.exe --help=warnings
참조

13. 자주 사용하는 옵션
• --title=<TEXT> : 문서 제목
• --footer=<TEXT> : 문서 하단 문구
• --welcome=<PATH> : 문서 오픈 시 첫 페이지에 보여줄 환영 HTML 파일

14. 자주 사용하는 어노테이션
• @auth : 코드 작성자
• @class : 클래스임을 선언한다.
• @constructor : 생성자임을 선언한다.
• @deprecated : 메소드나 필드를 추천하지 않는다.
• @docauthor : API 문서 작성자
• @param : 파라미터를 선언한다. 파라미터가 여러 개일 경우 반복해서 사용할 수 있다.
• @return : 반환되는 값을 선언 한다.
※ 위의 어노테이션 외에도 다양한 어노테이션들이 있는데, Ext-js만 사용되는 어노테이션들이 많다.
일반 자바스크립트 파일에는 적용되지 않는 것 같다.

15. • 예제
자주 사용하는 어노테이션

16. • 문서 화면
자주 사용하는 어노테이션

17. Q&A
• 질문은 jsduck wiki(https://github.com/senchalabs/jsduck) 로….