[Javadoc] @see 태그

@see 태그

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

@see reference

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

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

텍스트, 외부 링크

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

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

@see "string"

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

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

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

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

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

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

@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" 파일을 브라우저로 확인해 보자.

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

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