JavaDoc 주석 다는 방법, 기본적인 예

여전이 주석이라는 것에 대해 긍정적인 면보다는 부정적인 면이 더 많다고 생각하고 있지만.. 소스 코드와 주석을 통해 멋지게 문서를 자동으로 생성해 주는 개념은 주석에 대한 부정적인 많은 부분을 불식시키고도 남는듯합니다.

Java로 만든 어플리케이션(또는 서비스)의 소스를 협업자 또는 제3자에게 제공하기 위해 주석을 달때 JavaDoc의 도움을 받아 좀더 체계적으로 작업할 수 있도록 하기 위한 주석법입니다. 간단히 제 스스로 개발할때 참고하여 사용할만한 예제 코드로 정리해 봅니다.

먼저 클래스에 대한 주석의 예입니다.

/**
 * 화면상에 윈도우를 나타내기 위한 클래스
 * 사용 방법:
 *

 *    Window win = new Window(parent);
 *    win.show();
 *

 *
 * @author  Sami Shaio
 * @version 1.0
 * @see     java.awt.BaseWindow
 * @see     java.awt.Button
 */
class Window extends BaseWindow {
   ...
}

다음은 클래스의 필드에 대한 주석의 예입니다.

    /**
     * 컴포넌트의 X 좌표
     *
     * @see #getLocation()
     */
    int x = 1263732;

끝으로 클래스의 매서드에 대한 주석의 예입니다.

    /**
     * 지정된 index에 위치하는 문자 반환. 
     * index의 범위는 0에서 length() - 1까지임.
     *
     * @param     index  얻고자 하는 문자의 인덱스 값
     * @return      지정된 index의 문자
     * @exception StringIndexOutOfRangeException
     *     index가 0에서 length()-1의 범위를 벗어남
     * @see       java.lang.Character#charValue()
     */
    public char charAt(int index) {
       ...
    }