JAVA DOC을 사용하자.

JAVA DOC을 사용하자.

JLab 허원진

주석을 제대로 달면 소스 분석이 쉬워지고 유지보수가 쉽습니다. 자바를 위한 소스 문서화 솔루션인 JAVA DOC을 이용해서 문서를 만드는법을 알아보죠. 우선 한번 JAVA Documnet가 만들어지는 과정을 한번 살펴 보죠. 소스 주석 설명은 나중에 나옵니다. 일단 만드는 과정만 보세요.

JAVA DOC 주석을 사용한소스

/** * Study.java2002-07-25 * 루프와 제귀호출 성능 비교 * @author wonjin */ public class Study { public static void main(String[] args) { long temp; //수행시간 계산을 위한 임시변수 temp = System.currentTimeMillis(); for (int i = 0; i < 120000; i++) factorial1(200); System.out.println(System.currentTimeMillis() - temp); temp = System.currentTimeMillis(); for (int i = 0; i < 120000; i++) factorial2(200); System.out.println(System.currentTimeMillis() - temp); } /** * Method factorial1.팩토리알을 구한다, 루프 사용 * @param num 구 할 수 * @return long 결과 */ public static long factorial1(int num) { long result = 1; while (num > 1) { result *= num--; } return result; } /** * Method factorial1.팩토리알을 구한다, 제귀적호출 * @param num 구 할 수 * @return long 결과 */ public static long factorial2(int num) { if (num < 2) return 1; else return num * factorial2(num - 1); } }

이렇게 JAVA DOC주석 방식을 이용해서 코딩을 합니다. 그런 다음에는 javadoc을 이용해서 문서를 만들면 됩니다. javadoc은 J2SDK가 설치되어있는 bin 디렉토리에 있습니다. 위 소스가 있는 디렉토리로가서.

e:\ide\eclipse\workspace\study>javadoc study.java

이렇게 실행을 하면 도큐먼트가 만들어 집니다.

주의:bin디렉토리가 시스템 패스에 잡혀 있어야 합니다.

javdoc study.java -d e:\doc 이런 식으로 -d 옵션을 이용해서 만들경로를 지정 할 수 있습니다. 어떤것들이 만들어 졌는지 볼까요?

많이 만들어 졌네요. 하지만 index.html만 실행하면 소스에대한 문서를 볼수 있습니다.

JAVA DOC으로 만든 문서

Class Study java.lang.Object | +--Study public class Study extends java.lang.Object Study.java2002-07-25 루프와 제귀호출 성능 비교 Author: wonjin Constructor Summary Study()               Method Summary static long factorial1(int num)           Method factorial1.팩토리알을 구한다, 루프 사용 static long factorial2(int num)           Method factorial1.팩토리알을 구한다, 제귀적호출 static void main(java.lang.String[] args)               Methods inherited from class java.lang.Object equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait   Constructor Detail Study public Study() Method Detail main public static void main(java.lang.String[] args) factorial1 public static long factorial1(int num) Method factorial1.팩토리알을 구한다, 루프 사용 Parameters: num - 구 할 수 Returns: long 결과 factorial2 public static long factorial2(int num) Method factorial1.팩토리알을 구한다, 제귀적호출 Parameters: num - 구 할 수 Returns: long 결과

　

자 만드는법은 쉽죠? 이제 주석에 대해 알아 볼까요?

/**
* Study.java2002-07-25
* 루프와 제귀호출 성능 비교
* @author wonjin
*/

일반 주석 방식과는 조금 다릅니다. /**로 시작해서 */로 끝나죠 그리고 주석 내용 앞에는 * 가 꼭 있어야 합니다. 예약어 (@author 와같은 @시작하는)를 사용하지 않은 문장은 그대로 보여집니다.

public class Study

extends java.lang.Object

Study.java2002-07-25 루프와 제귀호출 성능 비교

하지만, 예약어를 사용한 문장은 구분 되어서 보여지죠.

Author:

wonjin

　

이제 메소드에 대한 JAVA DOC 주석을 볼까요?

/**
* Method factorial1.팩토리알을 구한다, 루프 사용
* @param num 구 할 수
* @return long 결과
*/

factorial2

public static long factorial2(int num)

Method factorial1.팩토리알을 구한다, 제귀적호출

Parameters:

num - 구 할 수

Returns:

long 결과

　

간단하네요. 일반적인 설명, @param 변수이름 설명, @return 리턴형 설명. 메소드에 대한 예약어는 더 있습니다. @throws 예외형 설명. 이 외에도 다른 예약어들이 있고 이 예약어들을 조합해서 문서를 만들면 됩니다.

더 자세한 내용을 알고 싶으면 http://java.sun.com/j2se/javadoc/index.html 에 방문해 보세요.

　

JAVA DOC Tag List

Overview Tags

@see @since @author @version {@link} {@linkplain} {@docRoot}

　

Package Tags

@see @since @deprecated @serial @author @version {@link} {@linkplain} {@docRoot}

　

Class/Interface Tags

@see @since @deprecated @serial @author @version {@link} {@linkplain} {@docRoot}

An example of a class comment:

/**
 * A class representing a window on the screen.
 * For example:
 * <pre>
 *    Window win = new Window(parent);
 *    win.show();
 * </pre>
 *
 * @author  Sami Shaio
 * @version %I%, %G%
 * @see     java.awt.BaseWindow
 * @see     java.awt.Button
 */
class Window extends BaseWindow {
   ...
}

　

Field Tags

@see @since @deprecated @serial @serialField {@link} {@linkplain} {@docRoot} {@value}

An example of a field comment:

    /**
     * The X-coordinate of the component.
     *
     * @see #getLocation()
     */
    int x = 1263732;

　

Method/Constructor Tags

@see @since @deprecated @param @return @throws and @exception @serialData {@link} {@linkplain} {@inheritDoc} {@docRoot}

An example of a method doc comment:

    /**
     * Returns the character at the specified index. An index 
     * ranges from <code>0</code> to <code>length() - 1</code>.
     *
     * @param     index  the index of the desired character.
     * @return    the desired character.
     * @exception StringIndexOutOfRangeException 
     *              if the index is not in the range <code>0</code> 
     *              to <code>length()-1</code>.
     * @see       java.lang.Character#charValue()
     */
    public char charAt(int index) {
       ...
    }