[JAVA] Javadoc 완벽 가이드

1. Javadoc이란?

Javadoc은 Java에서 제공하는 문서화 도구로, Java 소스 코드에서 특정 형식의 주석을 사용하여 자동으로 API 문서를 생성할 수 있도록 돕는다.

이를 통해 코드의 설명을 문서로 만들고, 개발자들이 쉽게 참조할 수 있게 한다.

 

✅ Javadoc의 주요 특징

• 자동 문서 생성: /** */ 주석을 사용하여 작성한 내용을 HTML 문서로 변환

• 클래스, 인터페이스, 메서드, 필드 설명 포함

• HTML 링크와 연계 가능하여 다른 클래스 및 메서드 간 참조 제공

• JDK 기본 라이브러리(예: String, ArrayList 등)도 Javadoc을 사용하여 문서화됨

 

 

 

---

2. Javadoc 주석 문법

Javadoc 주석은 /** */ 형태로 사용되며, 일반적인 /* */ 주석과는 다르다.

주석 내부에는 @태그를 사용하여 문서를 체계적으로 구성할 수 있다.

 

기본 문법

/**
 * 여기에 클래스, 메서드, 변수에 대한 설명을 작성한다.
 * 여러 줄에 걸쳐 설명 가능.
 *
 * @태그명 설명
 */

 

Javadoc 주석의 위치

Javadoc 주석은 클래스, 메서드, 필드(멤버 변수) 등의 앞에 작성된다.

/**
 * 사용자 정보를 저장하는 클래스
 */
public class User {

    /**
     * 사용자의 이름
     */
    private String name;

    /**
     * 사용자의 나이를 저장하는 변수
     */
    private int age;

    /**
     * 사용자의 이름과 나이를 설정하는 생성자
     *
     * @param name 사용자 이름
     * @param age 사용자 나이
     */
    public User(String name, int age) {
        this.name = name;
        this.age = age;
    }

    /**
     * 사용자의 이름을 반환하는 메서드
     *
     * @return 사용자 이름
     */
    public String getName() {
        return name;
    }
}

 

 

 

---

3. Javadoc 태그(Tag) 목록

Javadoc 주석 내부에서 @ 기호를 이용하여 다양한 정보를 추가할 수 있다.

 

✅ 주요 Javadoc 태그

태그	설명	사용 위치
@author	작성자 이름	클래스
@version	버전 정보	클래스
@since	특정 버전부터 사용 가능	클래스, 메서드
@param	메서드의 매개변수 설명	메서드
@return	메서드의 반환값 설명	메서드
@throws 또는 @exception	발생할 수 있는 예외 설명	메서드
@deprecated	해당 기능이 더 이상 사용되지 않음을 표시	클래스, 메서드
@see	관련 정보(클래스, 메서드) 링크 제공	클래스, 메서드
@link	코드 내에서 특정 클래스, 메서드 등을 참조하는 링크 추가	클래스, 메서드
@code	코드 블록을 문서에 포함	클래스, 메서드

 

 

 

---

4. Javadoc 태그 예제

 

(1) @author, @version, @since

/**
 * 사용자 정보를 저장하는 클래스
 *
 * @author Alex
 * @version 1.0
 * @since 2025-02-03
 */
public class User { }

 

(2) @param, @return, @throws

/**
 * 두 정수를 더하는 메서드
 *
 * @param a 첫 번째 정수
 * @param b 두 번째 정수
 * @return 두 정수의 합
 * @throws IllegalArgumentException 음수가 입력될 경우 예외 발생
 */
public int add(int a, int b) {
    if (a < 0 || b < 0) {
        throw new IllegalArgumentException("음수 입력 불가");
    }
    return a + b;
}

 

(3) @deprecated

/**
 * 사용자 나이를 반환하는 메서드
 *
 * @return 사용자 나이
 * @deprecated 이 메서드는 더 이상 사용되지 않으며, 대신 getAgeNew()를 사용할 것
 */
@Deprecated
public int getAge() {
    return age;
}

 

(4) @see

/**
 * 사용자 정보를 저장하는 클래스
 *
 * @see UserManager
 */
public class User { }

 

(5) @link

/**
 * 사용자 정보를 출력하는 메서드
 *
 * @see User#getName()
 * @see User#getAge()
 */
public void printUserInfo() {
    System.out.println("이름: " + getName());
    System.out.println("나이: " + getAge());
}

 

(6) @code

/**
 * 두 수를 곱하는 메서드
 *
 * 예제 코드:
 * <pre>
 * {@code
 * int result = multiply(2, 3);
 * System.out.println(result); // 출력: 6
 * }
 * </pre>
 *
 * @param a 첫 번째 숫자
 * @param b 두 번째 숫자
 * @return 곱셈 결과
 */
public int multiply(int a, int b) {
    return a * b;
}

 

 

 

---

5. Javadoc 문서 생성하기

Javadoc 문서는 javadoc 명령어를 사용하여 HTML 문서로 생성할 수 있다.

 

(1) Javadoc 생성 명령어

javadoc -d docs User.java

 

• -d docs : docs 폴더에 HTML 문서 생성

• User.java : Javadoc을 생성할 Java 파일

 

(2) 여러 개의 파일에서 Javadoc 생성

javadoc -d docs -sourcepath src -subpackages com.example

 

• -sourcepath src : src 폴더 내 소스 코드에서 Javadoc 생성

• -subpackages com.example : com.example 패키지의 모든 클래스 문서화

 

(3) Javadoc 옵션

옵션	설명
-d <디렉토리>	문서를 저장할 디렉토리 지정
-author	@author 태그 포함
-version	@version 태그 포함
-private	private 멤버도 문서화
-link	다른 Javadoc 페이지 링크 포함

 

 

 

---

6. Javadoc 문서 확인

 

Javadoc 문서를 생성하면 index.html 파일이 만들어지며, 이를 웹 브라우저로 열어 확인할 수 있다.

 

1. docs/index.html을 실행

2. 브라우저에서 Javadoc API 문서 확인

3. 생성된 문서에서 패키지, 클래스, 메서드 설명을 볼 수 있음

 

 

 

---

7. 정리

• Javadoc은 Java 코드의 문서화를 위한 도구

• /** */ 형식의 주석을 사용하여 자동 문서 생성 가능

• 다양한 @태그(@param, @return, @throws, @author 등) 지원

• javadoc 명령어를 사용하여 HTML 문서 생성 가능

• 개발자 간 코드 공유 및 유지보수에 필수적인 도구

 

Javadoc을 활용하면 코드 문서를 별도로 작성할 필요 없이, 코드 자체가 문서 역할을 수행할 수 있어 효율적인 개발이 가능하다. 🚀