バナー画像

Javadocとは?

Javadocは簡単に説明すると、Java言語のソースコードから「プログラムについて説明するドキュメント」を生成する仕組みです。

Javadoc用のコメントを記述すると、作ったプログラムに対するドキュメントをソースコードに埋め込んでくれます。

言葉だけで説明しても理解が難しいと思うので、具体的なコードを出して詳しく説明していきます。

 

例えば、値を2倍して結果を出力する以下のようなプログラムがあるとしましょう。

public class JavadocTest{

   public static int doubleFunc(int number){
      // 引数の10を2倍して返します
      return number * 2;
   }

   public static void main(String[] args){
      // numberにdouble関数の結果を代入します
      int number = doubleFunc(10);
      // 結果を出力します
      System.out.println(number);
   }

}

 

ソースコードには処理とコメントが記述されています。

コメントは、

// 引数の10を2倍して返します

のように、スラッシュ(/)2つで書かれている部分です。

スラッシュとアスタリスク(*)で囲んで、

/* 引数の10を2倍して返します */

とも書けます。

 

このソースコードに対して、コンピュータは以下の内容を読み取って処理します。

 

  1. クラスの名称は「JavadocTest」である
  2. 「JavadocTest」の中には、メソッド「main」と「double」がある
  3. 「main」は「String[] args」を受けて「void」を返す
  4. 「doubleFunc」は「int number」を受けて「int」を返す

 

コンピュータは処理を読み取るものの、コメントに書かれている内容やメソッドの中身はプログラムによって異なるので見ていないんです。

そこで、コンピュータに「このコメントはドキュメントに載せてね」と判断させるために用いられるのが「Javadoc用のコメント」になります。

Javadocの概要
  • Javadocは、「プログラムについて説明するドキュメント」を生成する仕組み
  • Javadoc用のコメントを記述すると、ドキュメントにコメントを反映させられる

Javadoc用のコメントの書き方

Javadoc用のコメントは、具体的にどのように記述すればいいのか知りたいです。

では、次にサンプルを見ながらコンピュータがどのように処理をするのか見ていきましょう。

Javadoc用のコメントは、スラッシュ(/)とアスタリスク(*)2つで始まるように「/**」で記述します。

/**
* これがJavadoc用のコメントの書き方です。
*/

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

 

また、Javadoc用のコメントの中で「@」は特殊な記号として認識されます。

「@author」と記述するとプログラムの制作者を意味し、「@version」と記述するとバージョンを意味するといった「Javadocタグ」が付けられます。

その他にもさまざまな種類のJavadocタグがあるので、後ほどご説明しますね。

 

Javadoc用のコメントを記述して、値を2倍して結果を出力するプログラムのソースコードを書き直すと、以下のようになります。

/**
* Javadoc用コメントのテストプログラム
* @author ポテパンスタイル
* @version 1.0.0
*/

public class JavadocTest{

   /**
   * doubleFuncメソッド
   * 引数を2倍にして返す
   * @param number 整数値
   * @return 引数を2倍した整数値
   */
   public static int doubleFunc(int number){
      // 引数の10を2倍して返します
      return number * 2;
   }

  /**
   * mainメソッド
   * doubleメソッドに引数を渡して結果を出力する
   */
   public static void main(String[] args){
      // numberにdouble関数の結果を代入します
      int number = doubleFunc(10);
      // 結果を出力します
      System.out.println(number);
   }

}

 

Javadoc用のコメントを追加したこのソースコードに対して、コンピュータは以下の内容を読み取って処理をします。

 

  1. クラスの名称は「JavadocTest」である
  2. 「JavadocTest」は「Javadocのテスト用クラス」である
  3. 「JavadocTest」を作ったのは「ポテパンスタイル」である
  4. 「JavadocTest」のバージョンは「1.0.0」である
  5. 「JavadocTest」の中には、メソッド「main」と「double」がある
  6. 「main」は「String[] args」を受けて「void」を返す
  7. 「main」は「mainメソッド」である
  8. 「main」は「doubleメソッドに引数を渡して結果を出力する」メソッドである
  9. 「doubleFunc」は「int number」を受けて「int」を返す
  10. 「doubleFunc」は「doubleFuncメソッド」である
  11. 「doubleFunc」は「引数を2倍にして返す」メソッドである
  12. 「doubleFunce」は「整数値」を受け取る
  13. 「doubleFunc」は「引数を2倍した整数値」を返す

 

以上のように、Javadocはソースコードから、

の2つを自動で抽出してまとめたドキュメントです。

このドキュメントを作成するときに使われるコマンド・プログラムとも言えます。

Javadocタグの種類と意味

Javadoc用のコメントの中には、「説明文」と「Javadocタグ」を記述することが可能です。

Javadocタグには以下の種類と意味があります。

 

Javadocタグ

 

意味

 

@author

 

作成者について指定します

 

@version

 

バージョンについて指定します

 

@see

 

「関連項目」として外部リンクやテキストを表示、他のフィールドやメソッドなどへの参照リンクについて指定します

 

@deprecated

 

クラスやメソッドなどを「非推奨」として指定します

 

@since

 

導入されたバージョンを指定します。「@version」タグは現在のバージョン、「@since」タグはどのバージョンから導入されているかを表す点が異なります

 

@param

 

パラメータに関する説明を指定します

 

@return

 

戻り値に関する説明を指定します

 

@throws(@exception)

 

発生する可能性のある例外に関する説明を指定します

 

{@link}

 

Javadocタグ中で、文字列を表示する場所の中に参照リンクを表示する場合に指定します

 

{@linkplain}

 

「{@link}」タグと同じだが、「{@link}」の文字列がコードテキストに対して、「{@linkplain}」タグはプレーンテキストで表示されます

 

Javadocドキュメントの作成方法

Javadocコマンドを使用してソースコードからドキュメントを作成する場合、以下のように実行すればドキュメントが作成できます。

$ javadoc -d html JavadocTest.java

 

作成が正常にできると、htmlという名前のディレクトリが作成され、ディレクトリ内に「index.html」というファイルがあります。

Webブラウザで開いて内容を確認すると、以下のようなHTML形式のドキュメントが生成されます。

Javadocの意味と書き方まとめ

Javadocの意味と書き方をご紹介していきました。

Javadocは、クラスやメソッドなど、Java言語の構成要素とその説明が対応づけられているため、多人数で開発をする場合などに役立ちます。

また、Javadocはフォーマットが決まっており、メソッド全体についてのコメントを書くため 意味のない情報を書くことが少なくなります。

Javadocが必要になったときは、ぜひこの記事を読んで有効活用してくださいね。

 

エンジニアになりたい人に選ばれるプログラミングスクール「ポテパンキャンプ 」

ポテパンキャンプは卒業生の多くがWebエンジニアとして活躍している実践型プログラミングスクールです。 1000名以上が受講しており、その多くが上場企業、ベンチャー企業のWebエンジニアとして活躍しています。

基礎的な学習だけで満足せず、実際にプログラミングを覚えて実践で使えるレベルまで学習したいという方に人気です。 プログラミングを学習し実践で使うには様々な要素が必要です。

それがマルっと詰まっているポテパンキャンプでプログラミングを学習してみませんか?

卒業生の多くがWebエンジニアとして活躍

卒業生の多くがWeb企業で活躍しております。
実践的なカリキュラムをこなしているからこそ現場でも戦力となっております。
活躍する卒業生のインタビューもございますので是非御覧ください。

経験豊富なエンジニア陣が直接指導

実践的なカリキュラムと経験豊富なエンジニアが直接指導にあたります。
有名企業のエンジニアも多数在籍し品質高いWebアプリケーションを作れるようサポートします。

満足度高くコスパの高いプログラミングスクール「ポテパンキャンプ」

運営する株式会社ポテパンは10,000人以上のエンジニアのキャリアサポートを行ってきております。
そのノウハウを活かして実践的なカリキュラムを随時アップデートしております。

代表の宮崎もプログラミングを覚えサイトを作りポテパンを創業しました。
本気でプログラミングを身につけたいという方にコスパ良く受講していただきたいと思っておりますので、気になる方はぜひスクール詳細をのぞいてくださいませ。