자바 독 주석(Javadoc) 마스터: 문서화 주석 작성과 태그 활용법

자바는 세 가지 주석 타입을 지원합니다: /* 블록 주석 */, // 줄 주석, 그리고 문서화 주석(/** ... */). Javadoc 도구는 문서화 주석에서 HTML 문서를 자동 생성합니다.

Javadoc이란?

JDK에 포함된 도구로, 소스 코드의 문서화 주석을 파싱하여 API 문서(HTML)를 생성합니다. 표준 형식을 따르면 클래스, 메서드, 필드, 패키지 설명을 체계적으로 정리할 수 있습니다.

기본 문서화 주석 구조

/**
 * 클래스/메서드/필드에 대한 설명 (첫 문장은 요약으로 사용됨)
 * <p>
 * 상세 설명은 HTML 태그 사용 가능 (<h1>, <p>, <code>, <ul> 등)
 *
 * @author 작성자명
 * @version 버전
 * @since 버전/날짜
 */
public class Example { ... }

주요 Javadoc 태그

실전 예제

/**
 * <h1>두 숫자 더하기 유틸리티</h1>
 * 두 정수를 더하는 간단한 기능을 제공합니다.
 * <p>
 * {@code null} 안전하지 않으며, 오버플로 검사하지 않습니다.
 *
 * @author 김개발
 * @version 2.1
 * @since 2023-01-15
 */
public class Adder {
    /**
     * 두 정수를 더합니다.
     *
     * @param a 첫 번째 피연산자
     * @param b 두 번째 피연산자
     * @return a + b의 합
     * @throws ArithmeticException 오버플로 발생 시 (Java 8+ Math.addExact 사용 권장)
     * @see Math#addExact(int, int)
     */
    public int add(int a, int b) {
        return a + b;
    }
    
    /**
     * 메인 진입점.
     * @param args 사용 안 함
     */
    public static void main(String[] args) {
        Adder adder = new Adder();
        System.out.println("10 + 20 = " + adder.add(10, 20));
    }
}

Javadoc 실행 및 옵션

# 기본 실행
javadoc Adder.java

# 주요 옵션
javadoc -d docs -sourcepath src -subpackages com.example \
        -author -version -private -encoding UTF-8 \
        -stylesheetfile custom.css

• -d: 출력 디렉터리

• -private: private 멤버까지 문서화

• -stylesheetfile: 커스텀 CSS 적용

모범 사례

• 모든 public/protected API에 문서화 주석 필수 작성

• 첫 문장은 간결한 요약으로 (자동으로 요약 테이블에 사용됨)

• {@code}로 코드 조각 감싸기 (HTML 이스케이프 자동)

• @param, @return, @throws 빠짐없이 작성

• 패키지 설명은 package-info.java에 작성

• CI/CD 파이프라인에 Javadoc 생성 단계 포함