[Java] Javadoc에 대해서 알아보자
프로젝트에 점점 살을 붙여가는 과정에서 신경쓰지 않던 /** */ 의 형태로 되어 있는 주석(?)을 보게되었다. 근데 일반적인 주석과 달리 @param @return에 색이 들어있는걸 보면서 무언가 기능이 있는 코드겠구나 싶어 찾아보았다.
해당 코드는 Javadoc이라는 걸 검색을 통해 알게되었고 이에 대해 찾아본 것들을 정리하려고 한다.
Javadoc이란
Javadoc은 JDK와 함께 패키지로 제공되는 도구로, JDK가 설치되어 있다면 사용할 수 있다.
Javadoc은 Java 소스 코드의 코드 문서를 생성하는 데 도움츨 주는 도구이다.
예를 들어 Javadoc은 html을 따로 작성하지 않고도 소스 코드에 작성된 코멘트를 따라 문서를 만들 수 있도록 한다. 또한 Javadoc에 따른 형식으로 작성해두면 일반적인 주석으로 읽을 수 있다.
Javadoc 작성 방법
기본적인 형식은 아래와 같이 사용한다.
/**
* 주석
* 주석
* 주석
*/Java에서 여러 줄의 주석을 쓸 때 쓰는 방법과 유사해보지만 첫 부분에 * 표시가 하나 더 붙는다.
기본적인 형태에서 이런 형식으로 작성할 수 있다.
/**
* 이 클래스, 또는 메소드에 대한 설명 글
* @param x x좌표
* @param y y좌표
* @return
*/Javadoc은 내부에서 크게 '설명문'과 '태그 섹션'으로 나뉜다.
설명문은 클래스 또는 메소드 등에 대해 간략하게 설명한 글이고, 여러 줄을 작성할 수 있다.
주석의 시작 부분에서 첫 번째 태그 섹션이 나타날 때까지의 영역이다. 또한, Html문으로 해석되기 때문에 단순히 행을 바꿔 작성하여도 줄바꿈이 되지 않고 명시적으로 <br>을 작성해야 줄바꿈이 일어난다.
태그 섹션은 @으로 시작하는 영역으로, 하나의 주석에 여러 종류를 동시에 작성할 수 있다.
또한 태그 섹션 이후로는 설명문을 작성할 수 없다.
Javadoc의 태그
@author 태그
- 클래스, 인터페이스 등에 작성하고 작성자를 지정하는 데 사용한다.
- 같은 주석 내에서 여러 번 지정할 수 있다.
@version 태그
- 클래스, 인터페이스 등에 작성학 소프트웨어의 버전을 지정하기 위해 사용한다.
- 같은 주석 내에서 여러 번 지정할 수 있다.
- 비슷한 태그로 @since가 있다.(현재 버전이 아닌 도입된 버전을 지정하는 경우에 사용)
→ Javadoc의 -version 옵션을 지정한 경우에만 출력된다.
@See 태그
- 관련 항목으로 외부 링크 또는 텍스트를 표시하거나, 다른 필드나 메소드에 대한 모든 참조 링크를 나타내는 경우에 사용한다.
- 즉, Html 문장의 <a> 태그와 같은 형식으로 링크 및 레이블을 지정하여 사용한다.
- 문자열을 표시할 경우, 쌍따옴표("")를 둘러싸서 지정해야 한다.
@deprecated 태그
- 클래스나 메소드 등의 사용을 더이상 권장하지 않는 경우에 사용한다.
- 즉, 차후에 없어질 수도 있다는 의미로 사용한다.
@param 태그
- 매개변수에 대한 설명을 표시할 때 사용한다.
- 설명 부분은 여러 줄에 걸쳐 작성할 수 있다.
- 설명문과 동일하게 Html로 작성된다.
@return 태그
- 반환 값에 대한 설명(데이터 유형 및 범위 등)을 표시할 때 사용한다.
@throws, @exception 태그
- 두 태그는 발생할 수 있는 예외에 대한 설명을 표시할 때 사용한다.
- 서로 이름만 다를 뿐 동일하게 사용된다.
{@link}, {@linkplain} 태그
- {@link} 태그
- 다른 Javadoc 태그 중에 참조 링크를 표시할 경우에 사용한다.
- 이전까지의 태그들은 블록 태그라 불리지만, {@link} 태그는 인라인 태그라고 한다.
- {}로 묶어 사용하는 수석을 설명문 안이나 다른 블록 태그 안의 문자열의 부분에 사용할 수 있다.
- 연결 문자열은 코드 텍스트로 표시된다.
- {@linkplain}
- {@link} 태그와 사용방법이 동일하다.
- 다른 Javadoc 태그에서 문자열을 표시할 위치에 참조링크를 표시할 경우에 사용한다.
- 링크가 된 문자열이 일반 텍스트로 표시된다.
/**
* Javadoc 샘플 테스트
*/
public class Sample2 {
/**
* 이름 설정
* 반환은 {@link Sample1#getName() getName}을 참조
*
* @param name 이름
*/
public void setName(String name) {
}
/**
* 이름 반환
* 설정은 {@link #setName(String)}을 참조
*
* @return 이름을 String으로 반환
*/
public String getName() {
return null;
}
}{@code} 태그
- Javadoc에 예제 코드 작성시 사용된다.
- 즉, 설명에 예제 코드를 첨부할 영역에 사용한다.
/**
* Javadoc 샘플 클래스 <br/>
*
* <pre>
* {@code
* Foo foo = new Foo*();
* foo.foo();
* }
* </pre>
*/
public class Sample3 {
}
Javadoc 출력
IntelliJ를 기준으로 Javadoc을 출력하는 방법은 매우 간단하다.
shift 버튼 2번 연타 → 'generate JavaDoc' 입력 → 옵션 선택 → Generate 선택
세부 옵션을 통해 어떤 클래스들을 Javadoc에 포함시킬지 지정할 수 있다.
전체 프로젝트에 적용할 수도 있고, Custom scope를 선택하여 포함할 파일을 Include하고 제외할 파일을 Exclude할 수 도 있다.
이후 파일이 저장될 경로를 설정하고, 접근 제한자를 어디까지 포함시킬지 선택한다.
다만, 가장 중요한 점은 아래의 내용을 (Other) command line arguments에 추가해야 인코딩 에러가 발생하지 않는다.
-encoding UTF-8 -charset UTF-8 -docencoding UTF-8
[ 참 고 ]