JavaDoc 주석이란?

JavaDoc은 Java 소스 코드로부터 API 문서를 생성하는 도구
특정 형식으로 작성된 주석(JavaDoc 주석)을 기반으로 HTML 형태의 문서를 자동으로 생성하여, 클래스, 인터페이스, 메서드, 필드 등의 API 스펙을 명확하게 기술

JavaDoc 주석은 /**로 시작하고 */로 끝난다. 여러 줄에 걸쳐 작성할 수 있으며, 일반적인 설명 외에도 특정 태그를 사용하여 추가적인 정보를 명시할 수 있다.

JavaDoc 주석의 기본 구조:

/**
 * 클래스 또는 인터페이스에 대한 일반적인 설명.
 * 여러 줄에 걸쳐 상세하게 작성할 수 있다.
 *
 * <p>추가적인 설명이나 예시를 포함할 수 있다.</p>
 */
public class MyClass {

    /**
     * 필드에 대한 설명.
     */
    private String myField;

    /**
     * 생성자에 대한 설명.
     *
     * @param parameterName 파라미터에 대한 설명.
     * @throws ExceptionName 발생할 수 있는 예외에 대한 설명.
     */
    public MyClass(String parameterName) throws Exception {
        // ...
    }

    /**
     * 메서드에 대한 설명.
     * 이 메서드는 특정 기능을 수행한다.
     *
     * @param arg1 첫 번째 인자에 대한 설명.
     * @param arg2 두 번째 인자에 대한 설명.
     * @return 반환 값에 대한 설명.
     * @throws IOException 발생할 수 있는 IOException에 대한 설명.
     * @see AnotherClass 관련 클래스 링크.
     * @since 1.0 이 기능이 추가된 버전 정보.
     * @deprecated 더 이상 사용되지 않는 기능이며, {@link #newMethod(String)}를 대신 사용하시오.
     */
    public String myMethod(int arg1, boolean arg2) throws IOException {
        // ...
        return null;
    }
}

주요 JavaDoc 태그:

• @author name: 클래스 또는 인터페이스의 작성자를 명시한다. 여러 명일 경우 여러 개의 @author 태그를 사용한다.
• @version text: 클래스 또는 인터페이스의 버전을 명시한다.
• @param parameterName description: 메서드 또는 생성자의 파라미터에 대한 설명. 각 파라미터마다 하나의 @param 태그를 사용한다.
• @return description: 메서드의 반환 값에 대한 설명. 반환 값이 void인 경우에는 사용하지 않는다.
• @throws exceptionName description 또는 @exception exceptionName description: 메서드 또는 생성자가 던질 수 있는 예외에 대한 설명. 각 예외마다 하나의 태그를 사용한다.
• @see fully-qualified-class-name#method-name: 관련 클래스, 인터페이스, 메서드에 대한 링크를 생성한다. # 뒤에 메서드 또는 필드 이름을 명시하여 특정 멤버에 대한 링크를 만들 수 있다.
• @since version: 해당 기능이 처음 도입된 버전을 명시한다.
• @deprecated description: 해당 API가 더 이상 사용되지 않음을 알리고, 대안으로 사용할 수 있는 API를 {@link} 태그를 사용하여 제시할 수 있다.
• {@link fully-qualified-class-name#member label}: 다른 API 요소에 대한 인라인 링크를 생성한다. label은 링크 텍스트로 사용되며, 생략하면 API 요소의 이름이 사용된다.
• {@code text}: 텍스트를 코드 글꼴로 표시한다. HTML 특수 문자를 이스케이프 처리한다.
• {@literal text}: 텍스트를 있는 그대로 표시한다. HTML 특수 문자를 이스케이프 처리하지 않는다. 주로 코드 예시나 특수 문자를 포함하는 설명을 작성할 때 유용하다.
• @serial description: 직렬화 가능한 클래스의 필드에 대한 설명을 명시한다.
• @serialField fieldName type description: serialData 태그로 문서화된 객체의 필드를 설명한다.
• @serialData description: 직렬화된 객체의 데이터 형식을 설명한다.

JavaDoc 생성 방법:

JDK에 포함된 javadoc 명령어를 사용하여 JavaDoc 주석으로부터 HTML 문서를 생성할 수 있다. 명령어 형식은 다음과 같다.

Bash

 

javadoc [options] [packagenames] [sourcefiles] [@files]

• options: 문서 생성에 대한 다양한 옵션을 지정할 수 있다 (예: 출력 디렉토리, 문서 제목 등).
• packagenames: 문서화할 패키지 이름을 지정한다.
• sourcefiles: 문서화할 Java 소스 파일 이름을 지정한다.
• @files: 문서화할 파일 목록을 포함하는 파일을 지정한다.

예시:

현재 디렉토리의 모든 .java 파일을 대상으로 JavaDoc 문서를 doc 디렉토리에 생성하려면 다음과 같이 실행한다.

Bash

 

javadoc -d doc *.java

IDE (IntelliJ IDEA, Eclipse 등)에서도 JavaDoc 생성을 위한 기능을 제공한다.

JavaDoc의 중요성:

• API 문서화: 라이브러리나 프레임워크를 개발할 때 API 사용 방법을 명확하게 전달하는 중요한 수단이다.
• 코드 이해도 향상: 코드 작성자와 사용자 모두에게 코드의 목적, 사용법, 주의사항 등을 명확하게 제공하여 이해도를 높인다.
• 유지보수 용이성: 시간이 흘러 코드가 변경되더라도 JavaDoc을 통해 최신 API 정보를 유지할 수 있어 유지보수에 도움이 된다.
• 협업 효율 증대: 여러 개발자가 함께 작업할 때 API 스펙을 명확하게 공유하여 협업 효율성을 높인다.

따라서, Java 프로젝트를 진행할 때 JavaDoc 주석을 꼼꼼하게 작성하는 것은 매우 중요한 습관이다.