Javascript 파일을 문서화하는 JSDoc

JSDoc - JavaScript Documentation Tool

Introduction

• JSDoc은 말그대로 JavaScript 파일을 분석해서 JavaScript 문서를 생성해주는 툴입니다.
  
• Javadoc을 기반으로해서 만들어졌습니다.
  
• 출력양식으로는 HTML, XML, XMI을 지원합니다.

Installation

1. JSDoc은 Perl로 만드어져있기 때문에, Window를 사용하시는 분들은 ActivePerl을 먼저 받으신 다음에 설치를 해주셔야 합니다.
   
2. XP의 '시작 >실행 >cmd'을 실행하여서 명령프롬프트를 띄웁니다 .
   
3. 프롬프트 상에서 PPM을 입력한 후 엔터를 눌러 Perl Package Manager를 실행시킵니다.
   
4. 다음의 "PPM> install HTML-Template"명령을 실행시켜서 HTML 템플릿을 설치합니다.
   
   
   
   
5. 설치가 완료되었으면 "PPM> quit"를 실행하여 PPM을 종료합니다.
   
6. JSDoc을 다운받아서 압축을 풀어줍니다.

여기까지 다되었으면 설치는 완료입니다.

Usage
실행하는 방법은 간단합니다. perl.exe를 사용하여, jsdoc.pl 파일을 실행시켜주면 됩니다.

perl.exe jsdoc.pl [OPTION값들] [JS소스파일] [Output디렉토리]

예) perl.exe jsdoc.pl -p -r sample.js ../output

옵션으로 줄 수 있는 항목들은 여러가지가 있습니다만, 세가지 정도면 충분할 것 같습니다.(^^ 저의 경우지만요)

-r  재귀적으로 지정한 디렉토리와 이하의 파일들까지 JSDoc으로 처리를 합니다.
-p  private 항목들도 출력합니다.
-d  출력할 디렉토리를 지정합니다. (디폴트로는 js_docs_out입니다.)

옵션항목 다보기

Usage: jsdoc [OPTIONS] <js sourcefiles and/or directories>+

-h | --help  : Show this message and exit
-r | --recursive : Recurse through given directories
-p | --private : Show private methods and fields
-d | --directory : Specify output directory (defaults to js_docs_out)
-q | --quiet : Suppress normal output

--page-footer : Specify (html) footer string that will be added to all docs
--project-name : Specify project name for that will be added to docs
--logo : Specify a path to a logo to be used in the docs
--project-summary : Specify a path to a text file that contains an overview summary of the project

--no-sources : Don't include the source code view
※ JavaScript 파일 자체를 Syntax Hightlighting해서 보여줍니다. JavaScript파일 중에서도 prototype.js의 상속구조를 쓴 경우, JavaDoc형식의 문서를 볼 수 없기 때문에 파일 자체를 보는 것도 도움이 되기도 하더군요.

--extensions : Provide a comma-separated list of file extensions to be considered as JavaScript source files
--nested-file-naming : Use package-style naming (i.e. keep directory names in the file path). This is useful if you have multiple files with the same name, but in different directories. This option is only useful if --recursive is also used.
--globals-name :  Specify a 'class name' under which all unattached methods will be classified. The defaults to GLOBALS
--format : Set the output format. The options are html, xml and xmi, defaulting to html. The others are currently alpha software.
--template-dir : Provide another directory containing HTML templates
--no-lexical-privates : Ignore "private" variables and functions that are lexically defined within constructors
--package-naming : Use packages, with a package being defined as a class that only contains nested classes and possibly static members.

이클립스에서 좀 더 쉽게 사용한다면, '이클립스 메뉴 > External Tools > External Tools'를 클릭해서 Externals Tools창을 띄운 다음에 Program항목에서 JSDoc항목을 등록합니다.

그리고, Location항목에는 perl.exe의 위치를 지정하시구요. Working Directory에는 JSDoc이 설치되어 있는 위치를 지정하신 다음에 Arguments로 jsdoc.pl -r -r -d 소스파일 출력위치를 지정해주시면 이클립스에서 바로 실행시킬 수 있습니다.

Problems
JSDoc에는 몇가지 문제점이 있습니다. Java의 경우 엄격한 문법구조로 인하여 문서화가 쉬운 반면에, JavaScript의 경우 동적인 언어라서 자동으로 문서화하기가 쉽지 않습니다.

그래서인지, Prototype.js로 작성한 파일들의 상속구조로 작성한 파일들의 경우 JSDoc으로 전혀 생성이 되지 않더군요. (예를 들자면 Object.extend({}, {});로 작성된구조.)

출처 : jinoxst님의 AJAX 강의 5-1장 - JSDoc 을 이용한 자바스크립트 다큐먼트 생성하기