[Java] Javadoc 이란?

1. Javadoc 이란?

- 선 마이크로 시스템즈에서 개발한 문서 생성기이다.

- 자바 소스코드로 HTML 포멧의 API 문서를 생성한다.

- HTML로 생성하는 이유는 하이퍼링크를 편하게 달기 위함이다.

- 컴파일 타임에는 모두 지워지니 성능 걱정은 할 필요 없다.

- 작성된 자바 코드를 잘 이해하고 유지보수 하기 위함이 목적이다.

 

2. Javadoc 주석의 구조

- /** 으로 시작한다.

- 첫줄은 메서드를 기술한다. 그 이후는 태그를 이용하여 설명하는 내용이다.

- @Param : 메서드의 파라미터들

- @return : 메서드의 리턴값

- @throw : 메서드가 던질 수 있는 예외

- @see : 더 보기

 

3. 유형별 Javadoc 살펴보기

1) 클래스

- 클래스의 바로 위에온다.

- import문 보다는 아래에 와야 한다.

//import statements

/**
 * @author     cho
 * @version    1.0.0
 * @since      1.0.0
 */
public class Test {
  // class body
}

 

2) 메서드

- (1) : 무슨 일을 하는지 짧고 간결하게 설명.

- (2) : 모든 세부사항이 설명될 수 있는 공간, 작성하지 않아도 됨.

- (3) : 태그를 이용해 input, output 등을 설명할 수 있다.

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

 

3) 변수

- 메서드와 작성법이 비슷한데, (3) 이 생략되었다.

/**
 * 변수에 대한 설명
 */
private int debug = 0;