Javadoc 태그

@author 태그

@author 태그는 클래스 클래스, 인터페이스 등에 작성하고, 작성자를 지정하는데 사용한다.

@author name-text

저자에 관하여 지정한다.

작성 위치 : 개요, 패키지, 클래스, 인터페이스
중복 작성 : 가능
출력 형식 : 작성자
기    타 : "-author" 옵션 필요

주로 클래스 등의 주석을 작성하고, 저자가 누구인지를 지정하는 경우에 사용한다. 같은 주석 내에서 여러 번 지정할 수 있다.

/**
 * 주석의 설명문
 * @author devkuma
 * @author kimkc
 */

@author 태그가 중복으로 작성된 경우는 출력 될 때 각각의 저자가 쉼표(,)로 구분하여 한 줄에 모와서 출력된다.

참고로 Javadoc의 -author옵션을 지정한 경우에만 출력이 된다. -author 옵션에 대해서는 -author 옵션 페이지를 참조하여라.

@author 태그 실습

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

/**
 * Javadoc 테스트용 클래스
 * @author devkuma
 * @author kimkc
 */
public class Sample05 {

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

    }
}

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

$ javadoc -d doc -author Sample05.java

생성된 “doc"디렉토리에 있는 “Sample05.html” 파일을 브라우저로 확인해 보자.

javadoc

클래스의 설명 부분에 “작성자(author)“로 @author에 작성한 이름이 표시되어 있다. @author 태그를 중복 지정하였기에 모와서 한줄로 표시된 것을 확인 할 수 있다.

@version 태그

@version태그는 클래스, 인터페이스 등에 작성하고 소프트웨어의 버전을 지정하기 위해 사용한다.

@version version-text

소프트웨어 버전을 지정한다.

작성 위치 : 개요, 패키지, 클래스, 인터페이스
중복 작성 : 가능
출력 형식 : 버전
기    타 : "-version" 옵션 필요

소프트웨어의 현재 버전을 지정하는 경우에 사용한다. 같은 주석 내에서 여러 번 지정할 수 있다.

/**
 * 주석의 설명문
 * 
 * @version 1.0
 * @version Project 2.0.1
 */

@version 태그가 중복으로 작성된 경우는 출력 될 때 각각의 버전이 쉼표(,)로 구분하여 한 줄에 모와서 출력된다.

비슷한 태그로 @since가 있는데, 이 태그는 현재 버전이 아닌 도입 된 버전을 지정하는 경우에 사용한다.

주의한 점은 Javadoc의 -version 옵션을 지정한 경우에만 출력이 된다. -version 옵션에 대해서는 -version 옵션 페이지를 참조하여라.

@version 태그 샘플

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

/**
 * Javadoc 테스트용 클래스
 *
 * @version 1.0
 * @version Project 2.0.1
 */
public class Sample06 {

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

    }
}

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

$ javadoc -d doc -version Sample06.java

생성된 “doc"디렉토리에 있는 “Sample06.html” 파일을 브라우저로 확인해 보자.

javadoc

클래스의 설명 부분에 “버전(version)“으로 @version에 작성한 버전이 표시되어 있다. @version 태그를 중복 지정하였기에 모와서 한줄로 표시된 것을 확인 할 수 있다.

@see 태그

@see태그는 관련 항목으로 외부 링크 또는 텍스트를 표시하거나, 다른 필드나 메소드에 대한 모든 참조 링크를 나타내는 경우에 사용한다.

@see reference

관련 항목으로 텍스트와 링크를 표시

작성 위치 : 개요, 패키지, 클래스, 인터페이스, 필드, 메소드
중복 작성 : 가능
출력 형식 : 관련 항목

텍스트, 외부 링크

@see 태그는 텍스트 및 외부 링크로의 사용한다. 그 사용 방법에 대해서 살펴 보도록 하겠다.

먼저 관련 항목의 위치 정보를 문자열을 표시하는 경우이다.

@see "string"

표시 할 문자열을 쌍따옴표(”")로 둘러 싸서 지정한다. 사용하는 방법은 다음과 같다.

/**
 * 주석의 설명문
 * @see "Java"
 */
 ```

다음은 외부 사이트로의 링크를 표시하는 경우이다.

```java
@see <a href="URL">label</a>

HTML 문장의 <a> 태그와 같은 형식으로 링크 및 레이블을 지정한다. 사용하는 방법은 다음과 같다.

/**
 * 주석의 설명문
 * @see <a href="http://www.devkuma.com">데브쿠마</a>
 */

@see태그가 중복으로 작성된 경우는 출력 될 때 각각의 링크 레이블이 쉼표(,)로 구분하여 한 줄에 모와서 출력된다.

@see 태그 실습

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

/**
 * Javadoc 테스트용 클래스
 *
 * @see "Java"
 * @see <a href="http://www.devkuma.com">데브쿠마</a>
 */
public class Sample07 {

    /**
     * 사이즈 설정
     *
     * @param width 폭
     * @param height 높이
     * @see <a href="https://www.google.com/">구글</a>
     */
    public void setSize(int width, int height) {

    }
}

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

클래스와 메소드에 @see태그를 사용하여 관련 정보를 표시되어 있다. ‘@see’ 태그를 중복 지정하였기에 모와서 한줄로 표시된 것을 확인 할 수 있다.

참조 링크

@see 태그의 또 다른 사용법으로 다른 필드나 메소드에 대한 참조 링크를 표시하기 위해 사용한다.

다른 필드나 메소드에 대한 참조 링크를 표시하는 경우이다.

@see package.class#member label

package.class#member 형식으로 지정한 다른 메소드에 대한 링크를 만든다. 링크 레이블로 label을 표시하고 있지만 “label"는 선택 사항이다. 생략한 경우는 대상 메소드명으로 표시된다.

/**
 * 주석의 설명문
 * @see Sample08_02#setSize(int, int) setSize
 */

위에서는 패키지명을 생략하였다. 이와 같이 패키지명을 생략하거나 클래스명까지 생략하여 작성된 경우에는 생략된 부분을 다음의 순서로 지정된 이름을 검색한다.

  1. 현재의 클래스 또는 인터페이스
  2. 외부를 둘러싸고 있는 클래스와 인터페이스 (가장 가까운 것으로 부터 검색)
  3. 슈퍼 클래스와 슈퍼 인터페이스 (가장 가까운 것으로 부터 검색)
  4. 현재 패키지
  5. import 패키지, 클래스 및 인터페이스 (import 문의 순서에 따라 검색)

항상 전체 이름으로 패키지에서 멤버까지를 지정하면 확실하겠지만, 주석이 너무 길어져 버리는 경우가 있다. 생략을 하게 되면 작성된 주석 부분을 간결하게 작성할 수 있다.

공식 자료에 의하면 다음과 같은 작성 방법이 있다.

현재 클래스의 멤버를 참조한다.

@see #field
@see #method(Type, Type,...)
@see #method(Type argname, Type argname,...)
@see #constructor(Type, Type,...)
@see #constructor(Type argname, Type argname,...)

현재 또는 import된 패키지의 다른 클래스를 참조한다.

@see Class#field
@see Class#method(Type, Type,...)
@see Class#method(Type argname, Type argname,...)
@see Class#constructor(Type, Type,...)
@see Class#constructor(Type argname, Type argname,...)
@see Class.NestedClass
@see Class

다른 패키지의 요소를 참조한다. (완전 확실)

@see package.Class#field
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type argname, Type argname,...)
@see package.Class#constructor(Type, Type,...)
@see package.Class#constructor(Type argname, Type argname,...)
@see package.Class.NestedClass
@see package.Class
@see package

실습

간단한 예를 실습해 보도록 하겠다.

/**
 * Javadoc 테스트용 클래스
 *
 * @see Sample08_02
 */
public class Sample08_01 {

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

    }
}
/**
 * Javadoc 테스트용 클래스
 *
 * @see Sample08_01
 */
public class Sample08_02 {

    /**
     * 폭 반환
     *
     * @return 폭
     * @see Sample08_01#setSize(int, int)
     * @see #getHeight()
     */
    public int getWidth() {
        return 0;
    }

    /**
     * 높이 반환
     *
     * @return 높이
     * @see Sample08_01#setSize(int, int)
     * @see #getWidth()
     */
    public int getHeight() {
        return 0;
    }
}

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

$ javadoc -d doc Sample08_01.java Sample08_02.java

생성된 “doc” 디렉토리에 있는 “Sample08_01.html” 파일을 브라우저로 확인해 보자.

javadoc

“Sample08_01” 클래스에 대해서는 주석으로 “Sample08_02” 클래스에 링크를 설정되어 있기에 “관련 항목"에는 “Sample08_02” 클래스에 대한 참조 링크가 표시되어 있다.

javadoc

그리고 “setSize"메소드에는 “Sample08_02"클래스의 “getWidth"메소드와 “getHeight"메소드에 링크가 설정되어 있다. 여기도 메소드의 “관련 항목"에는 각각의 메소드에 대한 참조 링크가 표시되어 있다.

@deprecated 태그

@deprecated 태그는 클래스나 메소드 등을 더 이상 사용이 권장하지 않는 경우에 사용한다. 사용이 권장되지 않는다는 것은 사용을 불가능하다는 것은 아니다. 다만 권장을 하지 않고 차후에 없어질 수도 있다는 것을 의미한다.

@deprecated deprecated-text

사용이 권장하지 않는 경우에 지정한다.

작성 위치 : 개요, 패키지, 클래스, 인터페이스, 필드, 메소드
중복 작성 : 불가능
출력 형식 : Deprecated. + 입력한 문자열

사용을 권장하지 않게 된 이유 등을 문자열로 작성한다. 사용 방법 다음과 같다.

/**
 * 주석의 설명문
 * @deprecated 다른 방법으로 대체되었다.
 */

또한, 대체하는 메소드나 클래스 등의 링크를 따라 지정한다. 링크 지정은 {@link} 태그를 사용한다.

/**
 * 주석의 설명문
 * @deprecated 다른 메소드로 대체되었다 {@link #setScale ()}
 */

@deprecated에 지정된 문자열은 “Deprecated.“라고 문자열과 함께 주석의 설명문 앞에 표시된다.

@deprecated 태그 실습

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

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

    /**
     * 사이즈 설정
     *
     * @param width 폭
     * @param height 높이
     * @see Sample08_02#getWidth()
     * @see Sample08_02#getHeight()
     * @deprecated 다른 메소드로 대체되었다 {@link #setScale(int, int)}
     */
    public void setSize(int width, int height) {

    }

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

    }
}

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

$ javadoc -d doc Sample09.java

생성된 “doc” 디렉토리에 있는 “Sample09.html” 파일을 브라우저로 확인해 보자.

javadoc

메소드에 “Deprecated.“가 먼저 나오고 @deprecated 태그로 작성한 내용이 표시되는 것을 볼 수 있다.

javadoc

@deprecated 태그로 작성한 내용은 주석의 설명문보다 앞에 표시되는 점에 주의하자.

※ 요즘에는 비권장 메소드나 클래스 앞에 코드로 @Deprecated 어노테이션을 넣는 것을 권장하고 있다.

@since 태그

@since 태그 도입된 버전을 표시하는 경우에 사용한다. @version 태그는 현재의 버전을 나타내는 반면 @since 태그는 어떤 버전에서 도입 되었는지 나타내는 점이 다르다.

@since since-text

도입 된 버전을 표시한다.

작성 위치 : 개요, 패키지, 클래스, 인터페이스, 필드, 메소드
중복 작성 : 가능
출력 형식 : 도입 된 버전

버전 등을 나타내는 문자열을 지정한다. 사용법은 다음과 같다.

/**
 * 주석의 설명문
 * @since 2.5.1
 */

@since 태그가 중복으로 작성된 경우는 출력 될 때 각각의 버전은 쉼표(,)로 구분하여 한 줄에 모와서 출력된다.

@since 태그 실습

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

/**
 * Javadoc 테스트용 클래스
 *
 * @since 2.5.1
 * @since Project 1.4A
 */
public class Sample10 {

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

    }
}

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

$ javadoc -d doc Sample10.java

생성된 “doc"디렉토리에 있는 “Sample10.html” 파일을 브라우저로 확인해 보자.

javadoc

@since 태그를 중복 지정하였기에 모와서 한줄로 표시된 것을 확인 할 수 있다.

@param 태그

@param태그는 매개 변수에 대한 설명을 표시 할 때 사용한다.

@param parameter-name description

매개 변수에 대한 설명을 표시한다.

작성 위치 : 메소드
중복 작성 : 가능
츌력 형식 : 매개 변수명 및 설명

@author 태그가 중복으로 작성된 경우는 출력 될 때 각각의 저자가 쉼표(,)로 구분하여 한 줄에 모와서 출력된다.

메소드의 매개 변수명과 매개 변수에 대한 설명을 작성한다. 사용 방법는 다음과 같다.

/**
 * 주석의 설명문
 * @param width 폭
 * @param height 높이
 */
 ```
설명 부분은 여러 줄에 걸쳐 작성   있다. 여러 줄에 걸쳐있는 것을 표현하는 방법은 특별한 작성법이 있는 것은 아니다.

```java
/**
 * 댓글의 설명
 * @param width 폭
 * width 대한 설명 2번째 줄
 * width 대한 설명 3번째 줄
 * @param height 높이
 */

@param 태그 실습

간단한 예를 실습해 보도록 하겠다.

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

    /**
     * 사이즈 설정
     *
     * @param width 폭<br>
     * 단위는 센티미터
     * @param height 높이
     */
    public void setSize(int width, int height) {

    }
}

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

$ javadoc -d doc Sample11.java

생성된 “doc” 디렉토리에 있는 “Sample11.html” 파일을 브라우저로 확인해 보자.

javadoc

여러 줄로 설명을 작성한 경우도 HTML 문서로 취급되는 것에 주의하자. 줄 바꿈 할 경우 <br> 등의 줄 바꿈에 대한 태그가 필요하다.

@return 태그

@return 태그는 반환 값에 대한 설명(데이터 유형 및 범위 등)을 표시 할 때 사용한다.

@return description

반환 값에 대한 설명을 표시

기술 위치 : 메소드
복수 작성 : 불가능
출력 형식 : 반환 값

메소드의 반환 값에 대한 설명을 작성한다. 사용 법은 다음과 같다.

/**
 * 주석의 설명문
 * @return 계산한 면적
 */

@return 태그 실습

간단한 예를 실습해 보도록 하겠다.

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

    /**
     * 사이즈 설정
     *
     * @param width 폭
     * @param height 높이
     * @return 계산한 면적
     */
    public int getSize(int width, int height) {
        return width * height;
    }
}

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

$ javadoc -d doc Sample12.java

생성된 “doc” 디렉토리에 있는 “Sample12.html” 파일을 브라우저로 확인해 보자.

javadoc

이 태그는 작성한 설명문이 그대로 표시 될 뿐이다.

@throws, @exception 태그

@throws 태그는 발생할 수 있는 예외에 대한 설명을 표시 할 때 사용한다. 그리고 @exception태그와 ‘@throws’태그는 태그 이름이 다를뿐 동일하게 사용한다.

@throws class-name description

예외에 대한 설명을 표시

작성 위치 : 메소드
중복 작성 : 가능
출력 형식 : Throws

메소드 내에서 발생하는 예외에 대한 예외 클래스 이름과 설명을 입력한다. 사용 방법은 다음과 같다.

/ **
 * 주석의 설명문
 * 
 * @throws java.io.FileNotFoundException 지정된 파일을 찾을 수 없습니다
 * /

클래스 이름은 전체 패키지명 까지 모두 지정되지만 패키지 이름이 생략된 경우에는 다음의 순서에 따라 검색한다.

  1. 현재의 클래스 또는 인터페이스
  2. 외부를 둘러싸고 있는 클래스와 인터페이스 (가장 가까운 것으로 부터 검색)
  3. 슈퍼 클래스와 슈퍼 인터페이스 (가장 가까운 것으로부터 검색)
  4. 현재 패키지
  5. import 패키지, 클래스 및 인터페이스 (import 문장의 순서에 따라 검색)

여러 @throws 태그가 지정되는 경우에는 각각이 다른 행으로 표시된다.

@throws, @exception 태그 실습

간단한 예를 실습해 보도록 하겠다.

import java.io.FileNotFoundException;
import java.io.IOException;

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

    /**
     * 파일 쓰기
     *
     * @throws FileNotFoundException 지정된 파일을 찾을 수 없습니다
     */
    public void writeToFile() throws FileNotFoundException {

    }

    /**
     * 파일 읽기
     *
     * @throws java.io.IOException 입출력 관련
     * @throws java.lang.SecurityException 보안 관련
     */
    public void readFromFile() throws IOException, java.lang.SecurityException {

    }

    /**
     * 파일 삭제
     *
     * @throws java.lang.SecurityException 보안 관련
     * @exception FileNotFoundException 지정된 파일을 찾을 수 없습니다
     */
    public void deleteFile() throws SecurityException {

    }

    /**
     * 파일 찾기
     */
    public void searchFile() throws FileNotFoundException {

    }

}

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

$ javadoc -d doc Sample13.java

생성된 “doc” 디렉토리에 있는 “Sample13.html” 파일을 브라우저로 확인해 보자.

javadoc javadoc

deleteFile 메소드는 @exception 태그로 작성한 항목도 @throws 태그를 작성했을 때와 동일하게 Throws에 표시되고 있다.

그리고 searchFile 메소드는 @throws 태그를 작성하지 않았지만, 발생할 수 있는 예외도 Javadoc를 자동으로 추출되어 표시되는 것을 볼 수 있다.

{@link} 태그는 다른 Javadoc 태그 중에 참조 링크를 표시 할 경우에 사용한다. 지금까지의 태그들은 모두 블록 태그라고 불리는 반면에 이 태그는 인라인 태그라고 한다. 인라인 태그는 {}로 묶어 사용하여 주석을 설명문 안이나 다른 블록 태그 안의 문자열의 부분에 사용할 수 있다.

{@linkplain} 태그는 {@link} 태그와 기본적인 사용법은 동일하다. 다른 Javadoc 태그에서 문자열을 표시 할 위치에 참조 링크를 표시 할 경우에 사용한다. 다른 점은 {@link} 태그를 사용하는 경우 연결 문자열은 코드 텍스트로 표시되는 반면, {@linkplain} 태그의 경우는 링크가 된 문자열을 일반 텍스트로 표시되는 점 뿐이다.

{@link package.class#member label}

블록 태그 안의 설명문이나 문자열 부분에서 참조 링크 표시

작성 위치 : 개요, 패키지, 클래스, 인터페이스, 필드, 메소드
중복 작성 : 가능

“package.class#member” 형식으로 지정하는 다른 메소드에 대한 링크를 만든다. 링크 레이블에 지정된 “label"이 표시되지만, “label"는 선택 사항이다. 생략한 경우는 대상 메소드명으로 표시된다. 기본적인 사용법은 @see 태그와 동일한다.

/ **
 * 주석의 설명문
 * 다음 메소드 {@link Sample14#setSize(int, int) setSize}를 참조
 * /

패키지명을 생략한 경우에 어떻게 링크를 검색하거나 대해서는 @see 태그 (참조 링크)를 참조하여라.

간단한 예를 실습해 보도록 하겠다.

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

      /**
       * 이름 설정
       * 반환은 {@link Sample14#getName() getName}을 참조
       *
       * @param name 이름
       */
      public void setName(String name){

      }

      /**
       * 이름 반환
       * 설정은 {@link #setName(String)}을 참조
       *
       * @return 이름을 String으로 반환
       */
      public String getName(){
          return null;
      }

}

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

$ javadoc -d doc Sample14.java

생성된 “doc” 디렉토리에 있는 “Sample14.html” 파일을 브라우저로 확인해 보자.

javadoc

먼저 {@link} 태그와 {@linkplain} 태그의 다른 확인해 보도록 하자. 위 문장은 {@link} 태그로 작성되어 코드 문자로 표시되고 있고, 아래 문장이 {@linkplain} 태그로 작성되어 기본 문자 글꼴 표시되고 있다.

코드 글꼴은 HTML <code>...</code> 태그로 묶인 경우에 적용되는 글꼴이고, 기본 문자 글꼴은 이 HTML 태그로 묶여 있지 않아서 표시 모양이 다르다. 링크로 표시되는 것은 동일하다.

javadoc

위와 같이 {@link} 태그와 {@linkplain} 태그는 설명문에 인라인 링크를 만들 때 사용하고, 링크를 참조로 별도 기준으로 표시 할 경우에는 @see 태그를 사용한다.

{@code} 태그

{@code} 태그는 Javadoc에 예제 코드 작성시 사용된다.

{@code source-code}

예제 코드 표시

작성 위치 : 개요, 패키지, 클래스, 인터페이스, 필드, 메소드
중복 작성 : 가능

설명에 예제 코드를 첨부할 영에 사용한다. 사용 방법 다음과 같다.

/**
 * 주석의 설명문
 * 
 * <pre>
 * {@code
 * Foo foo = new Foo();
 * foo.foo();
 * }
 * </pre>
 */

설명문에 예제 코드를 첨부할 경우 {@code} 태그만 사용해도 되지만, 줄바꿈이 필요할 시에는 HTML <pre> 태그를 같이 사용해야 한다.

{@code} 태그 실습

간단한 예를 실습해 보도록 하겠다.

/**
 * Javadoc 테스트용 클래스<br>
 *
 * <pre>
 * {@code
 * Foo foo = new Foo();
 * foo.foo();
 * }
 * </pre>
 */
public class Sample15 {

}

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

$ javadoc -d doc Sample15.java

생성된 “doc” 디렉토리에 있는 “Sample15.html” 파일을 브라우저로 확인해 보자.

javadoc

위와 같이 코드 글꼴로 표시되고 있다. 코드 글꼴는 HTML <code>...</code> 태그로 묶여 적용되는 글꼴이다.



최종 수정 : 2019-10-20