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

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

 

そもそもJavaについてよく分からないという方は、Javaとは何なのか解説した記事を読むとさらに理解が深まります。
 

なお本記事は、TechAcademyのオンラインブートキャンプJava講座の内容をもとに作成しています。

 

 

 

Javadocとは

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

 

Javadocの構造

Javadocは基本的に

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

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

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

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

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

例)

/** コメント */

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

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

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

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

@paramタグ

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

@returnタグ

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

@authorタグ

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

 

[PR] 未経験からWebエンジニアを目指す方法とは

実際に書いてみよう

/**
* 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やServletの技術を使ってWebアプリケーション開発を習得できるオンラインブートキャンプJava講座を開催しています。

挫折しない学習方法を知れる説明動画や、現役エンジニアとのビデオ通話とチャットサポート、学習用カリキュラムを体験できる無料体験も実施しているので、ぜひ参加してみてください。