[Javadoc] 주석의 구성

주석 서식

Javadoc로 생성되는 문서의 확인 및 Javadoc에 관련된 주석 작성 방법 등에 대한 Javadoc 기본 사항을 설명한다.

주석의 구성

Javadoc에 관계되는 주석의 구성에 대해 알아보자. 다른 페이지에서 확인 했듯이 주석는 다음과 같이 /**에서 */ 사이에 작성한다.

/**
 *
 * 이 사이에 주석을 작성한다.
 *
 */

주석 안은 크게 나누면 '설명문'과 '태그 섹션' 이렇게 두 가지로 구분할 수 있다.

설명문은 클래스 또는 메소드 등에 대해 간략하게 설명한 글이다.

/**
 * 이 클래스는 Javadoc 설명용 클래스이다.
 */

설명문에는 여러 분을 작성할 수 있다. 주석의 시작 부분에서 첫 번째 태그 섹션이 나타날 때까지가 설명문이 된다. 그러나 설명문은 HTML문으로 해석되기 때문에 단순히 행에 바꿔서 작성을 하여도 줄 바꿈되지 않고 표시된다. 명시적으로 줄 바꿈 할 경우 <br>을 작성해야 한다.

/**
 * 이 클래스는 Javadoc 설명용 클래스이다.
 * 여러 줄로 작성할 수 있다.
 * @version 2.0
 */

태그 섹션은 첫 번째 문자가 @로 시작한다. @version이나 @author 등 많은 javadoc 태그가 있으며, 각각 다른 의미를 가진다 (javadoc 태그의 자세한 내용은 다른 페이지에서 자세히 살펴 보겠다).

태그 섹션은 하나의 주석에 여러 종류를 동시에 작성 할 수 있다.

/**
 * 이 클래스는 Javadoc 설명용 클래스이다.
 * 여러 줄로 작성할 수 있다.
 * @version 2.0
 * @author devkuma
 */

태그 섹션에는 주석 중에 1번 밖에 사용 할 수 것과 여러 번 사용 할 수 있는 것이 있다. 여러 번 사용 할 수 있는 것에 대해서 계속 설명하도록 하겠다.

/**
 * 이 클래스는 Javadoc 설명용 클래스이다.
 * 여러 줄로 작성할 수 있다.
 * @version 2.0
 * @param string 이름
 * @param int 연령
 */

태그 섹션이 작성된 후에는 "설명문"을 작성 할 수 없다. 아래 내용은 잘못된 예를 보여준다.

/**
 * 이 클래스는 Javadoc 설명용 클래스이다.
 * 여러 줄로 작성할 수 있다.
 * @version 2.0
 * @param string 이름
 * @param int 연령
 * 설명문을 태그 섹션 이후에 작성하지 않는다.
 */

쌤플

그럼 간단한 예를 실습해 보도록 하자.

/**
 * Javadoc 테스트용 클래스
 * 여러 줄로 작성할 수 있다.
 */
public class Sample02 {
    /**
     * 사이즈 설정
     *
     * @param width 폭
     * @param height 높이
     */
    public void setSize(int width, int height) {

    }
}

그럼 위의 소스 코드를 "Sample02.java"라는 이름으로 저장하고 저장된 디렉토리에서 다음과 같이 실행해 보자.

$ javadoc -d doc Sample02.java

"doc" 디렉토리에 있는 "index.html"파일을 브라우저로 확인해 보자.

클래스에 대한 설명은 두 줄에 걸쳐 작성하였지만, <br>를 작성하지 않았기에 한줄로 표시되는 것을 볼 수 있다.