@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
*/
위에서는 패키지명을 생략하였다. 이와 같이 패키지명을 생략하거나 클래스명까지 생략하여 작성된 경우에는 생략된 부분을 다음의 순서로 지정된 이름을 검색한다.
- 현재의 클래스 또는 인터페이스
- 외부를 둘러싸고 있는 클래스와 인터페이스 (가장 가까운 것으로 부터 검색)
- 슈퍼 클래스와 슈퍼 인터페이스 (가장 가까운 것으로 부터 검색)
- 현재 패키지
- 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"메소드에 링크가 설정되어 있다. 여기도 메소드의 "관련 항목"에는 각각의 메소드에 대한 참조 링크가 표시되어 있다.
'Javadoc' 카테고리의 다른 글
| [Javadoc] @since 태그 (0) | 2019.10.20 |
|---|---|
| [Javadoc] @deprecated 태그 (0) | 2019.10.20 |
| [Javadoc] @see 태그 (0) | 2019.10.20 |
| [Javadoc] @version 태그 (0) | 2019.10.20 |
| [Javadoc] @author 태그 (0) | 2019.10.20 |
| [Javadoc] 주석 필드에 대한 주석 작성 시에 주의점 (0) | 2019.10.20 |
