[ 通常表示 ]  [ 簡易表示 ]  [ シンプル表示 ]

「分かりそう」で「分からない」でも「分かった」気になれるIT用語辞典イメージぴよ画像「分かりそう」で「分からない」でも「分かった」気になれるIT用語辞典

Javadoc

pointこの用語のポイント

pointJavaのソースコードの説明書だよ

pointホームページっぽい形になっているよ

pointソースコードから自動生成されるよ

pointソースコードの構造から読み取れる内容が記述されるよ

pointソースコード内に特定の書式で書いたコメントが記述されるよ

pointあるいは説明書を自動生成するプログラムだよ

pointあるいは説明書を自動生成するコマンドだよ

スポンサーリンク

簡単に書くよ

Javadocとは

ソースコードの内容から自動判定したり特定の書式で書かれたコメントを抜き出すことによって自動作成された、ホームページっぽい形式になっているJavaのソースコードの説明書。
あるいは

その説明書を作るのがお仕事のプログラム
であり

その説明書を作るときに使うコマンド
です。

image piyo

詳しく書くよ

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

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

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

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

Javadoc

この「とあるコマンドで自動作成されたソースコードの説明書」が「Javadoc」です。

Javadoc2

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

Javadoc3

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

Javadoc4

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

Javadoc5

Javadoc(説明書)に記載される内容は

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


の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);
   }

}


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

1.クラスの名前は「JavadocTest」
2.「JavadocTest」には、メソッド「main」と「testFunc」がある
3.「main」は「String[] args」をもらって「void」を返す
4.「testFunc」は「String inStr」をもらって「String」を返す


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

これが

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

です。
次に

2.特定の書式で書かれたコメント

について説明します。

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の内容は

1.クラスの名前は「JavadocTest」
2.「JavadocTest」には、メソッド「main」と「testFunc」がある
3.「main」は「String[] args」をもらって「void」を返す
4.「testFunc」は「String inStr」をもらって「String」を返す


から

1.クラスの名前は「JavadocTest」
[コ]1.「JavadocTest」は「Javadocのテスト用クラス」である
[コ]2.「JavadocTest」を作ったのは「ピヨ太」である
[コ]3.「JavadocTest」のバージョンは「1.0」である

2.「JavadocTest」には、メソッド「main」と「testFunc」がある
3.「main」は「String[] args」をもらって「void」を返す
[コ]4.「main」は「メイン」メソッドである
4.「testFunc」は「String inStr」をもらって「String」を返す
[コ]5.「testFunc」は「文字列を整形する」メソッドである
[コ]6.「testFunc」は「文字列」を受け取る
[コ]7.「testFunc」は「整形後文字列」を返す


となります。

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

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

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


の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」を開くと、それっぽい感じのホームページが表示されるはずです。

Javadoc6

それが、Javadocです。

image piyo2

一言でまとめるよ

まぁ「Javadoc」って単語が出てきたら「Javaのソースコードを元に自動生成されたソースコードの説明書、もしくは、その説明書を作るコマンド(プログラム)なんだな~」と、お考えください。

一番上に戻るよ
スポンサーリンク