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ソースコードにコメントを書く方法は次の2つである。

ブロックコメント

ブロックコメントは、/*から*/で囲まれた部分がすべてコメントになる。複数行を含めることができ、1行でも使用できる。

/*
  コメント
  コメント
*/

/* コメント */

1行コメント

1行にコメントを書く場合は//も使用できる。この場合、//の後ろから改行までがコメントになる。

// コメント

Javadocの対象になるコメントの書き方

Javadocを利用する場合でも、Javaソースコードに書くコメントと違いはないためJavaの規則に従う。ただし、Javadocドキュメント生成の対象にする場合は、次のように書く。

/**
  コメント
  コメント
*/

/** コメント */

/**から*/までに書かれた部分がJavadocの対象になる。

開始部分は/**で、通常のコメントの書き方である/*に比べて*が1つ多いが、/*のあとにコメントとして*が続いているのと同じなので、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、JavaScriptが生成されている。この中のindex.htmlファイルをブラウザで開いてみよう。

このように、ソースコードに書かれたコメントをもとにドキュメントが作成された。Javadocに対応した形式でコメントを追加するだけですぐにクラスやメソッドの仕様を作れるため、とても便利である。