Javadoc

Javadoc

• Javadoc의 문법과 주요 태그 사용법을 익힌다.
• 실제 클래스/메서드/필드에 주석을 작성할 수 있다.
• javadoc 명령어를 사용해 HTML API 문서를 생성할 수 있다.
• 팀원과 협업 시 읽기 쉬운 코드 문서를 작성하는 습관을 기른다.

습관

• 공개 클래스/메서드에는 반드시 Javadoc 작성
• @param 순서는 실제 매개변수 순서와 일치
• 팀 표준 정하기 (작성 필수 항목, 표현 방식 등)

• IntelliJ에서 Javadoc 자동 완성 사용하기: /** + Enter

---

1단계: Javadoc 기본 이해

Javadoc이란?

Javadoc은 Java 코드에 대한 설명을 문서화하기 위한 표준 주석 형식입니다.
이를 통해 자동으로 HTML 형태의 API 문서를 생성할 수 있으며, 대부분의 IDE(IntelliJ, Eclipse 등)에서 문서 툴팁으로도 활용됩니다.

• 목적:
  • 메서드, 클래스, 인터페이스의 기능 설명
  • 매개변수, 반환값, 예외에 대한 명확한 주석 제공
  • 자동 API 문서화

---

Javadoc 주석 구조

Javadoc은 일반적인 // 또는 /* */ 주석과는 다르게,
/** 로 시작해서 */로 끝나는 블록 주석입니다.

/**
 * 설명 부분 (요약 설명)
 *
 * 자세한 설명 (선택)
 * @param name 설명 대상 파라미터
 * @return 반환값에 대한 설명
 * @throws Exception 예외가 발생할 수 있는 경우
 */

⚠️ 중요한 포인트

• * 기호는 자동 정렬용이므로 IDE에서 자동으로 채워줍니다.
• @로 시작하는 부분이 태그, 이게 핵심입니다.

---

주요 태그 설명 및 예제

1. @param

• 메서드의 매개변수 설명
• 각 파라미터마다 @param 한 줄씩 써야 함

/**
 * 두 수를 더합니다.
 * @param a 첫 번째 정수
 * @param b 두 번째 정수
 */
public int add(int a, int b) {
    return a + b;
}

---

2. @return

• 메서드의 반환값 설명
• void 반환 타입에는 작성하지 않음

/**
 * 사용자 이름을 반환합니다.
 * @return 사용자 이름
 */
public String getName() {
    return this.name;
}

---

3. @throws 또는 @exception

• 예외가 발생할 수 있는 경우 설명
• 어떤 상황에서 예외가 발생하는지를 명확히

/**
 * 나눗셈을 수행합니다.
 * @param a 피제수
 * @param b 제수
 * @return 나눈 결과
 * @throws ArithmeticException b가 0일 경우
 */
public int divide(int a, int b) {
    if (b == 0) throw new ArithmeticException("0으로 나눌 수 없습니다.");
    return a / b;
}

---

4. @see

• 참조할 클래스, 메서드 링크
• 코드에서 연관된 내용을 연결할 때 사용

/**
 * 사용자 나이를 반환합니다.
 * @see #getName()
 * @see UserService#getUserById(int)
 */
public int getAge() {
    return this.age;
}

---

5. @deprecated

• 더 이상 사용하지 말아야 할 메서드 표시
• 새로운 대안 메서드를 링크와 함께 설명

/**
 * @deprecated 이 메서드는 v2부터 지원되지 않습니다. {@link #newMethod()}를 사용하세요.
 */
@Deprecated
public void oldMethod() {
    // ...
}

---

연습 과제

직접 Javadoc을 아래 메서드에 작성해보세요.

public int multiply(int a, int b) {
    return a * b;
}

public void login(String username, String password) throws AuthException {
    // 로그인 로직
}

---

 

2단계: 클래스, 생성자, 필드 주석 작성

---

1. 클래스에 대한 설명

클래스의 역할, 목적, 사용 예를 간단히 설명합니다. 주석은 클래스 선언 바로 위에 작성합니다.

/**
 * 회원 정보를 담는 도메인 클래스입니다.
 * 사용자의 이름, 나이, 이메일 정보를 포함합니다.
 */
public class User {
  // ...
}

---

2. 생성자에 대한 주석

생성자는 메서드처럼 @param 태그를 이용하여 매개변수 설명을 작성합니다.
@return은 작성하지 않으며, 생성자의 목적과 동작을 간단히 요약합니다.

/**
 * 이름과 나이를 받아 User 객체를 생성합니다.
 *
 * @param name 사용자 이름
 * @param age 사용자 나이
 */
public User(String name, int age) {
    this.name = name;
    this.age = age;
}

---

3. 필드에 대한 설명

필드에는 한 줄 주석 또는 Javadoc 주석 둘 다 가능하지만,
공개 필드(public)이나 문서화할 필요가 있는 경우에는 Javadoc을 사용하는 것이 좋습니다.

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

/** 사용자 나이 */
private int age;

※ 일반적으로 private 필드는 문서화 대상이 아니며,
외부 API로 제공되는 public/protected 필드나 상수에만 작성합니다.

---

클래스에 사용하는 주요 태그들

4. @author

• 클래스를 작성한 사람의 이름이나 이메일을 표시
• 팀 개발에서 책임자 표시 용도

/**
 * 사용자 정보를 관리하는 클래스입니다.
 * 
 * @author Heeseong
 */
public class User {
  // ...
}

---

5. @version

• 클래스 또는 API의 버전을 나타냅니다.
• 유지보수, 변경 이력을 추적할 수 있습니다.

/**
 * 사용자 정보를 관리하는 클래스입니다.
 *
 * @version 1.0.2
 */

---

6. @since

• 언제부터 이 클래스(또는 메서드)가 생겼는지를 표시
• 보통 릴리스 버전과 함께 사용합니다.

/**
 * 사용자 정보를 관리하는 클래스입니다.
 *
 * @since 2025.06.21
 */

---

종합 예시

/**
 * 사용자 정보를 저장하는 클래스입니다.
 * 이름, 이메일, 나이 등의 기본 정보를 포함합니다.
 *
 * @author Heeseong
 * @version 1.0.0
 * @since 2025-06-21
 */
public class User {

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

    /** 사용자 이메일 */
    private String email;

    /** 사용자 나이 */
    private int age;

    /**
     * 사용자 정보를 초기화합니다.
     *
     * @param name 사용자 이름
     * @param email 사용자 이메일
     * @param age 사용자 나이
     */
    public User(String name, String email, int age) {
        this.name = name;
        this.email = email;
        this.age = age;
    }

    // ... getter, setter 생략
}

---

연습 과제

아래 클래스를 보고 직접 Javadoc 주석을 작성해보세요:

public class Book {
    private String title;
    private String author;
    private int pages;

    public Book(String title, String author, int pages) {
        this.title = title;
        this.author = author;
        this.pages = pages;
    }
}

---

 

 

 

3단계: 고급 태그 및 링크 처리

---

1. @see

• 현재 클래스나 메서드와 관련 있는 다른 클래스, 메서드, 문서를 연결할 수 있습니다.
• HTML의 <a href> 링크처럼 동작합니다.
• 끝에 세미콜론(;)이 없습니다.

/**
 * 사용자 데이터를 처리하는 클래스입니다.
 * 
 * @see User
 * @see java.util.List
 */

---

2. {@link 클래스명#메서드명}

• 본문 중간에 하이퍼링크를 삽입할 때 사용합니다.
• 문서 내 다른 클래스/메서드로 바로 이동 가능하게 만듭니다.

/**
 * 사용자 목록을 반환합니다. 내부적으로 {@link UserService#findAll()} 을 호출합니다.
 */
public List<User> getUsers() {
    return userService.findAll();
}

• 괄호 안에는 다음 형식이 사용됩니다:
  • {@link java.util.List}
  • {@link #메서드명} (현재 클래스 내)
  • {@link 클래스명#메서드명} (외부 클래스)

---

3. {@code ...} 와 {@literal ...}

• {@code ...}: HTML 이스케이프 없이 코드처럼 출력 (monospace)
• {@literal ...}: <, > 같은 HTML 특수문자를 그대로 출력

/**
 * {@code if (a < b)} 형태의 비교문 예시입니다.
 * {@literal <p>} 태그는 단락을 만듭니다.
 */

---

4. 오버로딩 & 오버라이딩 메서드에 주석 다는 법

오버로딩(overloading)

• 파라미터가 다른 같은 이름의 메서드가 여러 개 있을 때 각각을 명확히 문서화해야 합니다.

/**
 * 주어진 이름으로 사용자 조회
 *
 * @param name 사용자 이름
 */
public User find(String name) { ... }

/**
 * 주어진 이름과 나이로 사용자 조회
 *
 * @param name 사용자 이름
 * @param age 사용자 나이
 */
public User find(String name, int age) { ... }

오버라이딩(overriding)

• 부모 클래스 메서드를 재정의할 경우, 기본 설명은 유지하되 추가된 부분만 명확히 주석 작성

/**
 * {@inheritDoc}
 * 
 * 관리자의 경우에는 결과가 필터링됩니다.
 */
@Override
public List<User> getUsers() {
    // ...
}

{@inheritDoc}은 부모 클래스나 인터페이스에 작성된 문서를 그대로 상속합니다.

---

5. 예외 처리 주석 @throws

• 메서드가 발생시킬 수 있는 예외에 대해 설명합니다.
• 예외 발생 조건과 예외 종류를 명시합니다.

/**
 * 사용자 ID로 조회
 *
 * @param id 사용자 ID
 * @return 사용자 객체
 * @throws UserNotFoundException 해당 ID의 사용자가 없는 경우
 */
public User findById(String id) throws UserNotFoundException {
    // ...
}

---

6. @deprecated와 대체 링크

• 더 이상 사용하지 않는 API에 사용
• 대체 API를 명확히 안내해야 함

/**
 * @deprecated 사용하지 마세요. 대신 {@link #findUserByEmail(String)} 를 사용하세요.
 */
@Deprecated
public User getUser(String id) { ... }

---

고급 태그 적용 전체 샘플

/**
 * 사용자 정보를 검색합니다.
 *
 * @param email 사용자 이메일
 * @return 사용자 객체
 * @throws IllegalArgumentException 이메일이 비어 있을 경우
 * @see UserRepository#findByEmail(String)
 * @see {@link #getUserById(String)}
 * @since 1.1
 */
public User findUserByEmail(String email) { ... }

/**
 * @deprecated 이 메서드는 {@code getUserByEmail()} 로 대체되었습니다.
 *             {@link #findUserByEmail(String)} 사용을 권장합니다.
 */
@Deprecated
public User getUser(String email) { ... }

---

연습 과제

아래 메서드를 보고 고급 Javadoc 주석을 직접 작성해보세요:

public class BookService {
    public Book find(String title) { ... }

    public Book find(String title, int year) { ... }

    public Book getBook(String isbn) throws BookNotFoundException { ... }

    @Deprecated
    public Book oldGetBook(String code) { ... }
}

---

 

4단계: javadoc 명령어로 문서 만들기

---

1. 기본 사용법

javadoc [옵션] [파일 or 패키지]

Javadoc 주석이 포함된 .java 파일을 분석하여 HTML 문서를 생성합니다.

예시: 단일 파일 문서 생성

javadoc MyClass.java

• MyClass.html 등의 문서가 생성됩니다.
• 같은 디렉토리에 index.html, allclasses.html 등도 함께 생성됩니다.

---

2. 디렉토리 단위(패키지 전체) 문서 생성

javadoc -d doc src/com/example/*.java

• src/com/example/에 있는 모든 .java 파일을 문서화
• 결과는 doc/ 디렉토리에 저장됩니다

---

3. 주요 옵션 정리

-d	문서 출력 디렉토리 지정
-author	@author 태그 출력 허용
-version	@version 태그 출력 허용
-private	private 멤버도 문서화
-protected	protected 멤버까지 문서화
-public	public 멤버만 문서화 (기본값)
-classpath	참조할 외부 라이브러리나 경로 지정
-subpackages	하위 패키지 포함하여 문서화
-encoding	소스 파일 인코딩 지정 (UTF-8 등)

---

4. 실무 예시 1: 프로젝트 전체 문서 생성

javadoc -d docs \
  -sourcepath src \
  -subpackages com.example.project \
  -author -version -encoding UTF-8

• src/com/example/project/... 전체를 문서화
• docs/ 폴더에 HTML 생성
• 하위 패키지까지 재귀적으로 포함
• @author, @version 태그 포함

---

5. 실무 예시 2: 외부 라이브러리 참조 필요할 때

javadoc -d docs \
  -classpath "lib/*:target/classes" \
  -sourcepath src \
  -subpackages com.example \
  -private

• lib/ 디렉토리의 모든 .jar와 target/classes를 classpath로 지정
• -private: 내부 구현까지 포함한 완전한 문서 생성

---

6. 생성 결과

문서 생성 후 docs/index.html을 열면 Javadoc 홈 페이지가 보이며, 다음이 포함됩니다:

• 클래스 계층 구조
• 패키지 별 클래스 목록
• 개별 클래스 문서 (MyClass.html)
• 인터페이스, 열거형, 예외 등도 함께 포함됨

---

 

 

5단계: 실습과 리팩토링

---

1. 본인 프로젝트에 Javadoc 작성

실습 과제

• Main.java, Service.java, Model.java 등 모든 주요 클래스에
  • 클래스 설명
  • 생성자, 필드, 메서드 주석 작성
  • 주요 태그 사용: @param, @return, @throws, @see, @since, @deprecated

---

2. docs/ 폴더에 HTML 문서화

javadoc -d docs -sourcepath src -subpackages com.example -encoding UTF-8 -author -version

• src/ 폴더 아래 모든 소스 코드 문서화
• docs/index.html 확인

---

3. Gradle을 이용한 Javadoc 자동화

build.gradle 설정 추가:

tasks.withType(Javadoc) {
    options.encoding = 'UTF-8'
    options.author = true
    options.version = true
    options.links("https://docs.oracle.com/javase/8/docs/api/")
}

task javadocJar(type: Jar) {
    dependsOn javadoc
    archiveClassifier.set('javadoc')
    from javadoc.destinationDir
}

실행:

./gradlew javadoc       # HTML 생성
./gradlew javadocJar    # javadoc 압축 파일 생성 (선택)

---

4. Maven을 이용한 Javadoc 자동화

pom.xml 설정 예시:

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>3.4.1</version>
      <configuration>
        <encoding>UTF-8</encoding>
        <show>private</show>
        <author>true</author>
        <version>true</version>
      </configuration>
    </plugin>
  </plugins>
</build>

실행:

mvn javadoc:javadoc

• 결과는 target/site/apidocs/index.html로 생성됩니다

---

5. GitHub Pages로 Javadoc 배포

1. docs/ 폴더에 HTML 생성

Gradle이나 CLI로 docs/ 폴더에 HTML 생성

2. GitHub Pages 설정

• GitHub에서:
  • "Settings > Pages" 메뉴에서
  • "Source"를 docs/ 폴더로 지정
• main 브랜치에 docs/ 커밋 후 push

git add docs
git commit -m "Add Javadoc docs"
git push origin main

3. 배포 확인

• https://your-username.github.io/your-repo-name/ 로 접속하여 문서 확인

---

마무리 리팩토링 팁

• Javadoc 커버리지 점검: 클래스 전체에 Javadoc 비율 높이기
• 자동화 스크립트 작성: generate-docs.sh 등의 스크립트로 CLI 명령 자동화
• CI/CD 연동: GitHub Actions로 push 시 Javadoc 자동 생성 + 배포 가능