Javadoc 만들기

1. Javadoc란

Javadoc은 Java 소스 코드로 HTML 형식의 문서를 생성한다.

Java 응용 프로그램을 만들 때, 유지 보수 등을 위하여 각 프로그램의 명세서를 작성해야 하는 경우가 있다. 소스 코드에 포함된 클래스와 메소드 등을 나중에 조사하여 명세서를 작성하기는 쉽지 않은 작업이다.

Javadoc는 JDK에 기본으로 포함된 프로그램으로 소스 코드에 포함된 클래스나 메소드의 주석(comment)으로부터 자동으로 명세서를 작성해 주는 편리한 도구이다.

Javadoc에 규칙에 따른 주석을 작성하는 방법을 학습하게 되면, Java 프로그래밍의 주석 작성에 대한 표준도 학습할 수 있다.

2. Java의 주석 작성 방법

1) 블록 주석

블록 주석은 /*에서 */로 둘러싸인 부분이 모든 주석이다. 여러 행을 포함할 수 있으며, 한 줄로도 사용할 수 있다.

/*
 주석
 주석
 */

/* 주석 */

2) 한 줄 주석

단일 행에 주석을 달 때 //도 사용할 수 있다. 이 경우 // 뒤에서 줄 바꿈까지가 주석이다.

// 주석

3. Javadoc의 대상이 되는 주석 작성 방법

Javadoc를 이용할 때에도 Java 소스 코드에 작성하는 것과 차이가 없으므로 Java 규칙을 따르지만, Javadoc 문서 생성의 대상으로 하는 경우에는 다음과 같이 작성한다.

/**
 주석
 주석
 */

/** 주석 */

/**에서 */까지, 작성된 부분이 Javadoc의 대상이 된다.

시작이 /**이고 일반적인 주석의 작성 방법인 /*에 비해 *가 하나가 많지만, /* 이후 주석으로 *가 이어서 작성되고 있는 것과 같기에 Java에서의 주석인 것에는 변함이 없다.

Java에서의 주석에서 특히 /**로 시작하는 것만을 대상으로 한다고 생각하면 된다.

또한 Javadoc에서는 여러 줄의 주석을 작성할 때는 각 줄 앞에 *가 작성되어 있던 경우는 제외하고 그 후에 문자열만을 주석의 대상으로 한다. 그리고 *이전에 작성된 공백이나 탭도 함께 제외된다.

따라서 Javadoc의 주석은 다음과 같은 작성 방법이 자주 사용된다.

/**
 * 주석
 * 주석
 * 주석
 */

위에 작성된 주석과 아래와 같이 작성한 주석은 같이 Javadoc에서 처리된다.

/**
 주석
 주석
 주석
 */

4. Javadoc 문서 작성

public class Sample01 {
    private int w;
    private int h;
    
    public Sample01() {
        w = 0;
        h = 0;
    }
    
    public void setSize(int width, int height) {
        w = width;
        h = height;
    }
    
    public int getWidth() {
        return w;
    }
    
    public int getHeight() {
        return h;
    }
}

이 샘플 코드에 대해서 Javadoc 주석를 작성한 예는 다음과 같다.

/**
 * Javadoc 테스트용 클래스
 *
 * @author devkuma
 * @version 1.0
 */
public class Sample01 {

    /**
     * 폭
     */
    private int w;

    /**
     * 높이
     */
    private int h;

    /**
     * 디폴트 생성자 클래스
     */
    public Sample01() {
        w = 0;
        h = 0;
    }

    /**
     * 사이즈 설정
     *
     * @param width 폭
     * @param height 높이
     */
    public void setSize(int width, int height) {
        w = width;
        h = height;
    }

    /**
     * 폭 반환
     *
     * @return 폭
     */
    public int getWidth() {
        return w;
    }

    /**
     * 높이 반환
     *
     * @return 높이
     */
    public int getHeight() {
        return h;
    }
}

위의 소스 코드를 ‘Sample01.java’라는 이름으로 저장하고 저장된 디렉터리에서 다음과 같이 실행한다.

$ javadoc -private -d doc Sample.java

실행한 디렉토리에 ‘doc’이란 디렉토리가 만들어 졌다. ‘index.html’ 파일을 브라우저에서 열어보면 다음과 같다.

이처럼 소스 코드에 쓰인 주석을 바탕으로 문서가 작성되었다. Javadoc에 대응 한 형태로 주석을 추가하는 것만으로 즉시 클래스 나 메소드 스펙을 만들 수 있으므로 매우 편리하다.

[출처 및 참고]

• https://www.devkuma.com/books/34