Javadoc 기본

Javadoc으로 생성된 문서

먼저 Javadoc의 사용법을 살펴 보기 전에 실제로 Javadoc로 생성된 문서의 예제를 살펴 보도록 하자.

JDK의 API 설명 페이지를 보도록 하자. (로컬 또는 온라인이든 상관 없다).

https://docs.oracle.com/javase/8/docs/api/

아래 명세서는 Boolean 클래스에 대한 내용이다.

이 API 설명 페이지에 표시되고 있는 이 HTML 페이지가 Javadoc로 생성된 문서이다. 이 문서는 Java 소스 코드에 작성된 코멘트에서 Javadoc을 사용하여 생성되었다.

이와 동일하게 자신의 소스 코드도 Javadoc에 따른 형식으로 주석을 작성하도록 해두면, 나중에 생성한 클래스 등에 관한 문서를 만들 수 있게 된다. 또한, Javadoc에 따른 형식으로 작성해 두면 일반적인 주석으로 읽을 수 있을 정도로 아무런 위화감도 없는 쉽고 간단한 형식으로 되어 있다.

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

주석을 작성하는 방법을 확인해 보자. Java로 코멘트를 작성하는 방법과, 그 중에서도 Javadoc의 대상이 되는 주석를 작성하는 방법에 대해서 설명하겠다.

Java의 주석 작성 방법

Java 소스 코드에 주석를 작성 방법은 다음 두 가지가 있다.

블록 주석

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

/*
  주석
  주석
*/

/* 주석 */

한 줄 주석

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

// 주석

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

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

/**
  주석
  주석
*/

/** 주석 */

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

시작이 /**이고 일반적인 주석의 작성 방법인 /*에 비해 *가 하나가 많지만, /* 이후 주석으로 *가 이어서 작성되고 있는 것과 동일하기에 Java에서의 주석인 것에는 변함이 없다. Java에서의 주석에서 특히 /**로 시작하는 것만을 대상으로 한다고 생각하면 된다.

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

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

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

/**
 주석
 주석
 주석
 */

Javadoc 문서 작성

실제로 문서를 만들어 보도록 하자. 아래는 간단한 Java 샘플 코드이다.

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 Sample01.java

$ javadoc -private -d doc Sample01.java
Loading source file Sample01.java...
Constructing Javadoc information...
Creating destination directory: "doc/"
Standard Doclet version 1.8.0_161
Building tree for all the packages and classes...
Generating doc/Sample01.html...
Generating doc/package-frame.html...
Generating doc/package-summary.html...
Generating doc/package-tree.html...
Generating doc/constant-values.html...
Building index for all the packages and classes...
Generating doc/overview-tree.html...
Generating doc/index-all.html...
Generating doc/deprecated-list.html...
Building index for all classes...
Generating doc/allclasses-frame.html...
Generating doc/allclasses-noframe.html...
Generating doc/index.html...
Generating doc/help-doc.html...

실행한 디렉터리에 “doc"이란 디렉터리가 만들어지고 다음과 같이 파일들이 생성되어 있다는 것을 확인할 수 있다.

$ ls -al
total 176
drwxr-xr-x  17 kimkc  staff    578 10  8 23:49 .
drwxr-xr-x   4 kimkc  staff    136 10  8 23:49 ..
-rw-r--r--   1 kimkc  staff  10937 10  8 23:49 Sample01.html
-rw-r--r--   1 kimkc  staff    633 10  8 23:49 allclasses-frame.html
-rw-r--r--   1 kimkc  staff    613 10  8 23:49 allclasses-noframe.html
-rw-r--r--   1 kimkc  staff   3507 10  8 23:49 constant-values.html
-rw-r--r--   1 kimkc  staff   3457 10  8 23:49 deprecated-list.html
-rw-r--r--   1 kimkc  staff   7892 10  8 23:49 help-doc.html
-rw-r--r--   1 kimkc  staff   5448 10  8 23:49 index-all.html
-rw-r--r--   1 kimkc  staff   2744 10  8 23:49 index.html
-rw-r--r--   1 kimkc  staff   3684 10  8 23:49 overview-tree.html
-rw-r--r--   1 kimkc  staff    740 10  8 23:49 package-frame.html
-rw-r--r--   1 kimkc  staff      1 10  8 23:49 package-list
-rw-r--r--   1 kimkc  staff   3906 10  8 23:49 package-summary.html
-rw-r--r--   1 kimkc  staff   3693 10  8 23:49 package-tree.html
-rw-r--r--   1 kimkc  staff    827 10  8 23:49 script.js
-rw-r--r--   1 kimkc  staff  12842 10  8 23:49 stylesheet.css

많은 HTML 파일과 css, js이 생성되어 있다. 이 중에 “index.html” 파일을 브라우저에서 열어보도록 하자.

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