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” 파일을 브라우저로 확인해 보자.
클래스의 설명 부분에 “작성자(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” 파일을 브라우저로 확인해 보자.
클래스의 설명 부분에 “버전(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
*/
위에서는 패키지명을 생략하였다. 이와 같이 패키지명을 생략하거나 클래스명까지 생략하여 작성된 경우에는 생략된 부분을 다음의 순서로 지정된 이름을 검색한다.
- 현재의 클래스 또는 인터페이스
- 외부를 둘러싸고 있는 클래스와 인터페이스 (가장 가까운 것으로 부터 검색)
- 슈퍼 클래스와 슈퍼 인터페이스 (가장 가까운 것으로 부터 검색)
- 현재 패키지
- 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"메소드에 링크가 설정되어 있다. 여기도 메소드의 “관련 항목"에는 각각의 메소드에 대한 참조 링크가 표시되어 있다.
@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” 파일을 브라우저로 확인해 보자.
메소드에 “Deprecated.“가 먼저 나오고 @deprecated 태그로 작성한 내용이 표시되는 것을 볼 수 있다.
@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” 파일을 브라우저로 확인해 보자.
@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” 파일을 브라우저로 확인해 보자.
여러 줄로 설명을 작성한 경우도 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” 파일을 브라우저로 확인해 보자.
이 태그는 작성한 설명문이 그대로 표시 될 뿐이다.
@throws, @exception 태그
@throws 태그는 발생할 수 있는 예외에 대한 설명을 표시 할 때 사용한다. 그리고 @exception태그와 ‘@throws’태그는 태그 이름이 다를뿐 동일하게 사용한다.
@throws class-name description
예외에 대한 설명을 표시
작성 위치 : 메소드
중복 작성 : 가능
출력 형식 : Throws
메소드 내에서 발생하는 예외에 대한 예외 클래스 이름과 설명을 입력한다. 사용 방법은 다음과 같다.
/ **
* 주석의 설명문
*
* @throws java.io.FileNotFoundException 지정된 파일을 찾을 수 없습니다
* /
클래스 이름은 전체 패키지명 까지 모두 지정되지만 패키지 이름이 생략된 경우에는 다음의 순서에 따라 검색한다.
- 현재의 클래스 또는 인터페이스
- 외부를 둘러싸고 있는 클래스와 인터페이스 (가장 가까운 것으로 부터 검색)
- 슈퍼 클래스와 슈퍼 인터페이스 (가장 가까운 것으로부터 검색)
- 현재 패키지
- 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” 파일을 브라우저로 확인해 보자.
deleteFile 메소드는 @exception 태그로 작성한 항목도 @throws 태그를 작성했을 때와 동일하게 Throws에 표시되고 있다.
그리고 searchFile 메소드는 @throws 태그를 작성하지 않았지만, 발생할 수 있는 예외도 Javadoc를 자동으로 추출되어 표시되는 것을 볼 수 있다.
{@link}, {@linkplain} 태그
{@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 태그 (참조 링크)를 참조하여라.
{@link}, {@linkplain} 태그 실습
간단한 예를 실습해 보도록 하겠다.
/**
* 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” 파일을 브라우저로 확인해 보자.
먼저 {@link} 태그와 {@linkplain} 태그의 다른 확인해 보도록 하자. 위 문장은 {@link} 태그로 작성되어 코드 문자로 표시되고 있고, 아래 문장이 {@linkplain} 태그로 작성되어 기본 문자 글꼴 표시되고 있다.
코드 글꼴은 HTML <code>...</code> 태그로 묶인 경우에 적용되는 글꼴이고, 기본 문자 글꼴은 이 HTML 태그로 묶여 있지 않아서 표시 모양이 다르다. 링크로 표시되는 것은 동일하다.
위와 같이 {@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” 파일을 브라우저로 확인해 보자.
위와 같이 코드 글꼴로 표시되고 있다. 코드 글꼴는 HTML <code>...</code> 태그로 묶여 적용되는 글꼴이다.