Javadocの作成方法を現役エンジニアが解説【初心者向け】

初心者向けにJavadocの作成方法について解説しています。Javadocを活用することでソースコード内のコメントからドキュメントを生成することができます。ここでは普通のコメントとの書き方の違いやJavadocタグの使い方を説明します。サンプルで動作を確認しましょう。

TechAcademyマガジンはオンラインのプログラミングスクールTechAcademy [テックアカデミー]が運営する教育×テクノロジーのWebメディアです。初心者でもすぐ勉強できる記事が2,000以上あります。

Javadocの作成方法について解説します。実際にプログラムを書いて説明しているので、ぜひ理解しておきましょう。

 

なお本記事は、TechAcademyのJava講座の内容をもとに作成しています。

 

 

田島悠介

今回は、Javaに関する内容だね!

大石ゆかり

どういう内容でしょうか?

田島悠介

Javadocの作成方法について詳しく説明していくね!

大石ゆかり

お願いします!

 

Javadocとは

JavadocはJavaのコードから生成することができるドキュメントです。コード書き加えたコメントをもとに生成します。ファイル形式はHTMLで、ブラウザで開いてみることができます。

 

Javadocの構造

Javadocは基本的に

  • フィールドのサマリー
  • コンストラクタのサマリー
  • メソッドのサマリー
  • フィールドの詳細
  • コンストラクタの詳細
  • メソッドの詳細

という要素で構成されています。例えばクラスフィールドが存在しない場合等それらの項目は作成されません。

通常のJavaのコメントとの違いは「/」の後に「*」が2つ書かれているところがポイントです。Javaのコメントの記載のルールとしては「*」が1つでも正しいですが、Javadocの対象にはならないので要注意です。

Javadocはソースコードとコメントをもとに作成されますが、コメントには記述ルールがあります。

「/**」を冒頭に記載、末尾は「*/」とします。以下の形式で記述します。

例)

/** コメント */

/**
コメント1行目
コメント2行目
*/

/**
* コメント1行目
* コメント2行目
*/

Javaのコメント「//」や「/*」はjavadoc生成用のコメントとしてみなされない為、使い分けに注意が必要です。

又、コメント内にJavadocタグと呼ばれるタグを利用することでドキュメント内の項目を生成すっることができます。代表的なものに以下のタグがあります。

@paramタグ

メソッドのパラメータ名と、そのパラメータに対する説明を記述します。

@returnタグ

メソッドの戻り値に対する説明を記述します。

@authorタグ

主にクラスのコメントに記述し、クラスの作成者が誰であるかを記述します。

 

[PR] Javaで挫折しない学習方法を動画で公開中

実際に書いてみよう

/**
* Javadocを生成するクラスです。
* @author taro yamada
*
*/
public class Sample {

  /**
  * クラスフィールドです。
  */
  static String s;

  /**
  * mainメソッドです。
  * printMessageメソッドを呼び出します
  */
  public static void main(String[] args) {

    s = "Javadoc生成確認";

    printMessage(s);

  }

  /**
  * printMessageメソッドです。
  * @param str 出力したい文字列を指定
  * @return 出力した文字列
  */
  static String printMessage(String str) {

    //コンソール出力
    System.out.println(str);
    return str;

  }
}

eclipseでjavadocを出力するときは

  1. 「ファイル」>「エクスポート」でエクスポート画面を開く
  2. 「Java」>「Javadoc」>「次へ」
  3. javadocに出力対象の要素と宛先を指定し「完了」

指定したディレクトリにに.html拡張子のついたファイルが出力されます。内容を確認すると上記コードとそのコメントに対応した内容でドキュメントが作成されていることが確認できます。

尚、コード中、

//コンソール出力

というコメントを記述していますが「//」はjavadoc出力対象のコメント形式ではないので、出力されません。

 

監修してくれたメンター

長屋雅美

独立系SIerで7年勤務後、現在はフリーのエンジニアとして自宅をオフィスとして活動しています。
JavaやC♯、shellscriptを用いた開発を主に担当し、TechAcademyではJavaコースを担当しています。

 

大石ゆかり

内容分かりやすくて良かったです!

田島悠介

ゆかりちゃんも分からないことがあったら質問してね!

大石ゆかり

分かりました。ありがとうございます!

オンラインのプログラミングスクールTechAcademyでは、Java講座を開催しています。

JavaやServletの技術を使ってWebアプリケーションの開発を学ぶことができます。

現役エンジニアがパーソナルメンターとして受講生に1人ずつつき、マンツーマンのメンタリングで学習をサポートし、最短4週間で習得することが可能です。

また、現役エンジニアから学べる無料のプログラミング体験会も実施しているので、ぜひ参加してみてください。