「分かりそう」で「分からない」でも「分かった」気になれるIT用語辞典

順番に見ていきましょう。

Javaはプログラミング言語のひとつです。
プログラムの元ネタ（ソースコード）を書くときに使う言葉です。

実はJavaには、すんばらし～機能が付いていましてね。
とあるコマンドを実行すると、ソースコードの説明書を自動で作ってくれるのです。

例えば「このメソッド（関数）には、こんな値を渡しますよ～」や「このメソッドからは、こんな値が返ってきますよ～」あるいは「このクラスには、こんなメソッドがありますよ～」などの情報がまとめられた、ホームページっぽい形の説明書を自動作成してくれます。



この

とあるコマンドで自動作成されたソースコードの説明書

が「Javadoc」です。



あるいは、Javadocを作るときに使う「とあるコマンド」が「Javadoc」です。
説明書を作るときには「javadoc」というコマンドを使います。



あるいは、Javadocコマンドを実行したときに、実際にお仕事をするプログラムが「Javadoc」です。
Windowsの場合は「javadoc.exe」という名前の実行ファイルが本体です。



早口言葉みたいですね。
Javadoc（説明書）を作るときにはJavadoc（コマンド）を実行します。
Javadoc（コマンド）を実行するとJavadoc（プログラム）が動きます。



Javadoc（説明書）に記載される内容は

１．ソースコードの構造から機械的に読み取れるもの
２．特定の書式で書かれたコメント

の2つです。

例えば、以下の内容のソースコードが あったとしましょう。

public class JavadocTest{

   public static String testFunc(String inStr){
      return "hoge:" + inStr;
   }

   public static void main(String[] args){
      String str = testFunc("aaa");

      System.out.println(str);
   }

}

コンピュータさんは、ソースコードから以下の内容を読み取ります。

１．クラスの名前は「JavadocTest」
２．「JavadocTest」には、メソッド「main」と「testFunc」がある
３．「main」は「String[] args」をもらって「void」を返す
４．「testFunc」は「String inStr」をもらって「String」を返す

メソッドの中身とかは読み取りません。
とても自動判定できないからです。
処理の部分は、プログラムごとに異なりますからね。

これが

１．ソースコードの構造から機械的に読み取れるもの

です。
次に

２．特定の書式で書かれたコメント

について説明します。

Javaのソースコードの中にはコメントを書けます。
コメントは「ソースコードに書く人間様用のメモ書き」です。
コンピュータさんは、書かれている内容を無視します。

普通のコメントを書くときには、スラッシュ（/）を2つ書いて

// これはコメントです。

と書くか、スラッシュ（/）とアスタリスク（*）で囲んで

/* これはコメントです。 */

/* これは複数行のコメントです。
2行目です。 */

のように書きます。
これは基本的に、他のプログラミング言語でも同じです。

ただし、JavaにはJavadoc用のコメントがあります。
スラッシュ（/）とアスタリスク（*）2つで始まるコメントは、コンピュータさんが「あぁ、このコメントは説明書に載せたいのね」と判断してくれるのです。
例えば

/**
* これはJavadoc用のコメントです。
*/

と書くと、Javadoc用のコメントと認識されます。

それを踏まえて、先ほどのソースコードにJavadoc用のコメントを追加してみました。
追加後のソースコードは以下の通りです。

/**
* Javadocのテスト用クラス
* @author　ピヨ太
* @version　1.0
*/
public class JavadocTest{

   /**
   * testFunc
   * 文字列を整形する
   * @param　inStr 文字列
   * @return　整形後文字列
   */
   public static String testFunc(String inStr){
      return "hoge:" + inStr;
   }

   /**
   * メイン
   */
   public static void main(String[] args){
      String str = testFunc("aaa");

      System.out.println(str);
   }

}

追加したJavadoc用のコメントは、クラス「JavadocTest」の補足説明

/**
* Javadocのテスト用クラス
* @author　ピヨ太
* @version　1.0
*/

と、メソッド「testFunc」の補足説明

/**
* testFunc
* 文字列を整形する
* @param　inStr 文字列
* @return　整形後文字列
*/

と、メソッド「main」の補足説明

/**
* メイン
*/

です。

これらの内容がJavadocに記載されることによって、Javadocの内容は

１．クラスの名前は「JavadocTest」
２．「JavadocTest」には、メソッド「main」と「testFunc」がある
３．「main」は「String[] args」をもらって「void」を返す
４．「testFunc」は「String inStr」をもらって「String」を返す

から

１．クラスの名前は「JavadocTest」
[コ]１．「JavadocTest」は「Javadocのテスト用クラス」である
[コ]２．「JavadocTest」を作ったのは「ピヨ太」である
[コ]３．「JavadocTest」のバージョンは「1.0」である
２．「JavadocTest」には、メソッド「main」と「testFunc」がある
３．「main」は「String[] args」をもらって「void」を返す
[コ]４．「main」は「メイン」メソッドである
４．「testFunc」は「String inStr」をもらって「String」を返す
[コ]５．「testFunc」は「文字列を整形する」メソッドである
[コ]６．「testFunc」は「文字列」を受け取る
[コ]７．「testFunc」は「整形後文字列」を返す

となります。

いかがでしょう。
かなり説明書っぽくなりましたよね？

このように、ソースコードから

１．ソースコードの構造から機械的に読み取れるもの
２．特定の書式で書かれたコメント

の2つを自動的に抜き出して、まとめた説明書がJavadocです。
もしくは、この説明書を作るときに使うコマンド・プログラムがJavadocです。

以上で説明は終わりですが、最後に、実際のJavadocを作るサンプルを書いておきます。
Javaの環境が手元にある人は、気が向いたら試してみてください。

まず、以下の内容のソースコードを「JavadocTest.java」の名前で保存します。

■JavadocTest.java
/**
* Javadocのテスト用クラス
* @author　ピヨ太
* @version　1.0
*/
public class JavadocTest{

   /**
   * testFunc
   * 文字列を整形する
   * @param　inStr 文字列
   * @return　整形後文字列
   */
   public static String testFunc(String inStr){
      return "hoge:" + inStr;
   }

   /**
   * メイン
   */
   public static void main(String[] args){
      String str = testFunc("aaa");

      System.out.println(str);
   }

}

次に、パスが通っている状態で以下のコマンドを実行します。

javadoc -author -version JavadocTest.java

「-author」は「@author」も書き出してね！なオプションです。
「-version」は「@version」も書き出してね！なオプションです。
よく分からなかければ、つけないで

javadoc JavadocTest.java

としても かまいません。

コマンドを実行すると、ごちゃごちゃとファイルができるはずです。
その中から「index.html」をWebブラウザ（ホームページを見るときに使うソフト）で開きます。
単に「index.html」を、べちべちっ！とダブルクリックしても かまいません。

「index.html」を開くと、それっぽい感じのホームページが表示されるはずです。



それが、Javadocです。