JavaScript를 JavaDoc처럼 생성해주는 JSDoc 설치 및 사용방법

Eclipse에서 Java 파일들에 대해 JavaDoc을 생성하는 방법은 지난 포스팅에서 살펴보았다. 하지만 이건 말그대로 Java 파일들에 대해서 할 수 있다. JavaScript라서 혹시 되나 해봤는데 역시 안된다. 

하지만 역시 이세계는 없는게 없다. JS 파일을 JSDoc으로 생성해주는 tookit이 있었고 사용법을 공유하고자 한다. 

 

Toolkit Download & Install

Google Code Archive - Long-term storage for Google Code Project Hosting.

위의 사이트에서 툴킷을 다운받을 수 있다. Windows, Linux, MacOS 관계없이 사용이 가능하다. 제일 위에 있는 파일을 받으면 된다. 

 

 

jsdoc-tookit install

 

설치파일을 받고 적당한 위치에서 압축을 풀어준다. 그럼 위와 같은 모습으로 나오는데 README 파일이 있고 여기에 사용하기 위한 방법이 적혀 있다. 열어보자. 

 

README.txt

======================================================================

REQUIREMENTS:

JsDoc Toolkit is known to work with:
java version "1.6.0_03"
Java(TM) SE Runtime Environment (build 1.6.0_03-b05)
on Windows XP,
and java version "1.5.0_19"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_19-b02-304)
on Mac OS X 10.5.

Other versions of java may or may not work with JsDoc Toolkit.

======================================================================

USAGE:

Running JsDoc Toolkit requires you to have Java installed on your
computer. For more information see http://www.java.com/getjava/

Before running the JsDoc Toolkit app you should change your current
working directory to the jsdoc-toolkit folder. Then follow the
examples below, or as shown on the project wiki.

On a computer running Windows a valid command line to run JsDoc
Toolkit might look like this:

> java -jar jsrun.jar app\run.js -a -t=templates\jsdoc mycode.js

On Mac OS X or Linux the same command would look like this:

$ java -jar jsrun.jar app/run.js -a -t=templates/jsdoc mycode.js

쭉 길게 어떤 사양에서 동작을 하는지 어떻게 사용을 하는지 등에 대한 정보가 기술되어 있다. 마지막에 있는 사용법대로 사용을 해보자. 

 

사용법

D:\tool\jsdoc_toolkit-2.4.0\jsdoc-toolkit>java -jar jsrun.jar app\run.js -a -e=utf-8 -t=templates\jsdoc C:\temp
Picked up JAVA_TOOL_OPTIONS: -Djava.net.preferIPv4Stack=true

내 상황에 맞게 위와 같이 실행을 해준다. 하나의 파일을 JSDoc으로 생성을 해줄때는 파일을 지정하면 되고 JS파일을 여러개 한번에 하고 싶다면 폴더째로 지정을 해주면 된다. 

 

C:\temp 하위에는 sample.js 파일이 있다. 이 파일은 다음과 같은 모습이다. 주석부분만 유심히 보자. 

/**
 * 날짜 유효성 체크
 * 
 * @param 날짜
 */
function gfn_checkDateValidation(date){
	if (date.length != 10){
		return false;
    }
	
	//들어가는지 유효성검사
	var date_pattern = /^(19|20)\d{2}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[0-1])$/; 
	if(!date_pattern .test(date)){
		return false;
	}
	date = date.replaceAll(/-/gi, "");
	var nYear = Number(date.substr(0, 4));
    var nMonth = Number(date.substr(4, 2));
    var nDay = Number(date.substr(6, 2));

    // 해당달의 마지막 일자 구하기
    var nMaxDay = new Date(new Date(nYear, nMonth, 1) - 86400000).getDate();
    if (nDay < 1 || nDay > nMaxDay){
    	return false;
    }
    
	return true;
}

 

그리고 -a, -e, -t 에 대한 옵션이 있는데 이는 다음과 같다. 

USAGE: java -jar jsrun.jar app/run.js [OPTIONS] <SRC_DIR> <SRC_FILE> ...

OPTIONS:
  -a or --allfunctions
          Include all functions, even undocumented ones.

  -c or --conf
          Load a configuration file.

  -d=<PATH> or --directory=<PATH>
          Output to this directory (defaults to "out").

  -D="myVar:My value" or --define="myVar:My value"
          Multiple. Define a variable, available in JsDoc as JSDOC.opt.D.myVar.

  -e=<ENCODING> or --encoding=<ENCODING>
          Use this encoding to read and write files.

  -E="REGEX" or --exclude="REGEX"
          Multiple. Exclude files based on the supplied regex.

  -h or --help
          Show this message and exit.

  -m or --multiples
          Don't warn about symbols being documented more than once.

  -n or --nocode
          Ignore all code, only document comments with @name tags.

  -o=<PATH> or --out=<PATH>
          Print log messages to a file (defaults to stdout).

  -p or --private
          Include symbols tagged as private, underscored and inner symbols.

  -q or --quiet
          Do not output any messages, not even warnings.

  -r=<DEPTH> or --recurse=<DEPTH>
          Descend into src directories.

  -s or --suppress
          Suppress source code output.

  -S or --securemodules
          Use Secure Modules mode to parse source code.

  -t=<PATH> or --template=<PATH>
          Required. Use this template to format the output.

  -T or --test
          Run all unit tests and exit.

  -u or --unique
          Force file names to be unique, but not based on symbol names.

  -v or --verbose
          Provide verbose feedback about what is happening.

  -x=<EXT>[,EXT]... or --ext=<EXT>[,EXT]...
          Scan source files with the given extension/s (defaults to js).

이중 -t는 Required 이니 빼면 실행이 되지 않는다. 

 

결과 확인

 

 

결과는 tookit 설치한곳의 out 폴더에서 확인할 수 있다. 들어가서 생성된 index.html을 눌러보자. 

 

 

JSDoc index.html

 

JavaDoc과 거의 비슷한 모습으로 JSDoc이 생성이 되었다. 잘 뽑아 내려면 JS 파일의 주석을 표준에 잘 맞게 작성을 하도록 하자. 

 

끝!