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>를 작성하지 않았기에 한줄로 표시되는 것을 볼 수 있다.

HTML문 작성

Javadoc으로 작성된 문장은 HTML 문으로 해석되어 표시된다. 반대로 말하면 HTML 문으로 작성해야 한다면, 태그가 아닌 문자 코드로 작성해야 한다. 예를 들어 <는 <로 작성해야 한다.

HTML 문장이기에, HTML 태그를 사용할 수 있다.

/**
 * 주석은 <b>HTML문</b>으로 작성한다.
 */

HTML 태그를 사용할 수 있지만 클래스 및 패키지 이외의 부분에서 <h1>과 <h2>등과 같은 제목 태그는 사용하지 않는 편이 좋을거 같다.

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

/**
 * Javadoc <b>테스트</b>용 클래스
 * <a href="http://www.devkuma.com" target="_blank">링크</a> 작성
 * <p style="color : #ff0000">스타일 시트</p> 작성
 */
public class Sample03 {

    /**
     * <font color="#ff0000">사이즈</font> 설정
     *
     * @param width 폭
     * @param height <font color="#0000ff">높이</font>
     */
    public void setSize(int width, int height) {

    }
}

위에 소스 코드를 “Sample03.java"라는 파일명으로 저장하고 저장된 디렉터리에서 다음과 같이 실행한다.

$ javadoc -d doc Sample03.java

“doc"디렉터리에 있는 “Sample03.html” 파일을 브라우저로 확인해 보자.

위와 같이 <b> 태그에 의한 강조와 <a> 태그로 링크, <p>로 스타일 시트, <font color="#0000ff">에 의한 색상의 지정이 잘 반영되는 것을 확인할 수 있다.

필드에 대한 주석 작성 시에 주의점

Java에서는 동일한 데이터 형식의 여러 필드를 한 번에 선언 할 수 있다.

int width, height;

이런 형식에 대해서 주석을 작성하게 되면 다음과 같이 작성이 될것이다.

/**
 * 폭과 높이를 나타낸다.
 */
int width, height;

이 경우는 두 변수에 같은 주석이 적용된다. 결과적으로 다음과 같이 작성했을 경우와 동일하다.

/**
 * 폭과 높이를 나타낸다.
 */
int width;

/**
 * 폭과 높이를 나타낸다.
 */
int height;

경우에 따라서는 이러한 형식으로도 문제없는 경우도 있겠지만, 대부분의 경우는 적절한 주석가 되지 않는다. 그러기에 Javadoc를 이용하는 경우에는 필드마다 선언하고, 별도의 주석을 하도록 한다.

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

/**
 * Javadoc 테스트용 클래스
 */
public class Sample04 {

    /**
     * 폭과 높이를 나타낸다.
     */
    public int width, height;

    /**
     * 사이즈 설정
     *
     * @param width 폭
     * @param height 높이
     */
    public void setSize(int width, int height) {

    }
}

위에 소스 코드를 “Sample04.java"라는 파일명으로 저장하고 저장된 디렉터리에서 다음과 같이 실행한다.

$ javadoc -d doc Sample04.java

“doc"디렉터리에 있는 “Sample04.html” 파일을 브라우저로 확인해 보자.

여러 필드가 한 번에 선언되어 한개의 주석을 작성하게 되면, 각각의 필드에 같은 주석이 표시된다.