JavaDoc :: 자바 API 문서

 

JavaDoc
선 마이크로 시스템즈에서 개발한 문서 생성기로, 자바 소스코드로 HTML 포맷의 API 문서를 생성한다. HTML 로 생성하는 이유는 하이퍼링크를 편하게 달기 위함이다. 컴파일 타임에는 모두 지워지니 성능 걱정은 할 필요 없다. 작성된 자바 코드를 잘 이해하고 유지보수 하기 위함이 목적이다.

 

 

Javadoc 주석의 구조
/** 로 시작한다.
첫 줄은 메서드를 기술한다. 그 이후는 태그를 이용하여 설명하는 내용이다.

@param: 메서드의 파라미터들
@return: 메서드의 리턴값
@throw: 메서드가 던질 수 있는 예외
@see: 더 보기

 

 

유형별 JavaDoc

1. 클래스

 - 클래스의 바로 위에 온다. import 문보다는 아래에 와야 한다.

//import statements

/**
 * @author     n00nietzsche@gmail.com
 * @version    1.0.0
 * @since      1.0.0
 */
public class Test {
  // class body
}

 

 

2. 메서드

(1): 무슨 일을 하는지 짧고 간결하게 설명한다.
(2): 모든 세부사항이 설명될 수 있는 공간이다. 작성하지 않아도 된다.
(3): 태그를 이용해 input output 등을 설명할 수 있다.
Javadoc 은 결국 HTML 을 결과로 뱉어내므로, HTML 태그를 이용한 줄바꿈 등이 유효하다.

/**
 * 1줄 짜리 간결한 설명 ------- (1)
 * <p>
 * 긴 설명 ----------------- (2)
 * <p>
 * HTML 로 줄바꿈하며 이어지는 설명이 있으면 더 한다.
 *
 * @param - 변수 설명 텍스트 - (3)
 * @return - 반환 값 설명 텍스트
 */
public int methodName (...) {
  // method body with a return statement
}

 

 

3. 변수

//권장하는 방식
/**
 * 포인트의 수평 거리이다.
 */
public int x;
/**
 * 포인트의 수직 거리이다.
 */
public int y;

//권장하지 않는 방식
/**
 * 포인트의 수평과 수직 거리이다.
 */
public int x, y; // 여러개 동시 선언은 기피해야 함

 

 

JavaDoc Tags

@author 이름	클래스나 인터페이스의 제작자 표시
@version 테스트	클래스나 인터페이스에서의 버전 정보
@param 매개변수 - 이름 설명	매개 변수에 대한 설명
@return 설명	메소드가 void를 리턴하거나 생성자가 아닌 경우를 제외하고 모두 사용해야 함
@exception or @throws	메소드가 발생시킬 수 있는 예외를 기술
@deprecated	다음 버전에서 폐기된 메소드를 알림
@serial	기본적으로 직렬화 할 수 있는 클래스의 멤버를 설명
@see	- 어떤 클래스, 인터페이스, 메소드, 생성자 혹은 URL에 대한 전후 참조 표시  - 분리된 줄에 링크가 생김
@since	Tag를 가진 객체가 언제 추가되었는지 명시
{@link #entity label}	메소드나 필드의 상호 참조에 대한 링크를 표시 문서 텍스트 안에 링크가 생김
{@doc-root}	문서에 대한 루트디렉토리에 대한 상대경로 지정

 

 

JavaDoc 사용법

1. Window > Show View > Other...

 

 

2. Javadoc 검색하면 사용할 수 있다