Javadocコメントとは。使用方法などを説明！！

javadocコメントというのは、

/**
 *
 */

ものすごく簡単に言うと、これです。

クラスやメソッドの上によくあるやつですね。
絶対に書いた方がいいです。

これを書いているか書いていないかで、
コードの読みやすさが全然違います。

さらにjavadocコメントを書くことで、
プログラムの仕様書にもなります。

今回はjavadocコメントの使い方などを
紹介していきます。

javadocコメントを書くとどうなるか
1. javadocコメントサンプル
2. javadocコメントが無いサンプル
javadocの生成（Eclipse使用）
1. 生成手順

javadocコメントを書くとどうなるか

一言で言うと、コードが読みやすくなります。

なぜか。

「Hello World！！」
を表示するプログラムを例に説明しましょう。

javadocコメントサンプル

めちゃちゃ簡単な例です。

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * Spring起動時に走リまーす
 * @author 著者でーす
 *
 */
@SpringBootApplication
public class HelloWorldApplication {

	public static void main(String[] args) {
		SpringApplication.run(HelloWorldApplication.class, args);

		var HelloWorld = new HelloWorld();
		String helloWorld = HelloWorld.SetHelloWorld();

		System.out.println(helloWorld);
	}
}

package com.example.demo;

/**
 * Hello World作りまーす
 * @author 著者でーす
 *
 */
public class HelloWorld {

	/**
	 * Hello World!!の文字列を作成
	 * @return Hello World!!
	 */
	public String SetHelloWorld() {

		String helloWorld = "";

		helloWorld += "Hello";
		helloWorld += " ";
		helloWorld += "World!!";

		return helloWorld;
	}
}

このようなjavadocコメントが書いてある、
「Hello World!!」と表示されるコードがあったとします。

mainメソッドを追っていた時、
18行目の

String helloWorld = HelloWorld.SetHelloWorld();

の上に差し掛かったとします。

この時、
このメソッドはどういうメソッドなのだろうと、
メソッドの上にポインターを合わせると、

このような感じに、
メソッドの説明や返り値、返り値の型などを表示してくれます。

このメソッドは、比較的わかりやすいメソッドなので、
そこまでありがたみを、感じにくいかもしれませんが、
現場に行くと、メソッドが複雑化してしまうことや
修正で他人が書いたコードを読まないといけない時が必ずあります。

そんな時に、javadocコメントが
あるのと無いのとでは大きな差です。

javadocコメントが無いサンプル

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class HelloWorldApplication {

	public static void main(String[] args) {
		SpringApplication.run(HelloWorldApplication.class, args);

		var HelloWorld = new HelloWorld();
		String helloWorld = HelloWorld.SetHelloWorld();

		System.out.println(helloWorld);
	}
}

package com.example.demo;

public class HelloWorld {

	public String SetHelloWorld() {

		String helloWorld = "";

		helloWorld += "Hello";
		helloWorld += " ";
		helloWorld += "World!!";

		return helloWorld;
	}
}

この時、同様に、

String helloWorld = HelloWorld.SetHelloWorld();

ここにカーソルを合わせてみます。

このように、javadocコメントが無い場合、
返り値の方しか表示されません。

これだと、このメソッドで何をしているのかが、
すぐには分かりにくいです。

javadocの生成（Eclipse使用）

javadocコメントは、書いていると
そのソースの仕様書のようなものをhtmlファイルで生成することができます。

サンプル↓

上記のクラス列はリンクとなっており、
クリックして中を見ることができます。

そして、説明欄などにコードで書いておいたjavadocコメントが反映されます。

javadocコメントを書いておくだけで、簡単な仕様書を作成することができるのです。

実際の動作が見たい方は、以下のGitHubにコードとhtmlファイルを載せているので
こちらでもご確認ください。

GitHub - tkmttkm/javadocSample: javadocサンプル用

javadocサンプル用. Contribute to tkmttkm/javadocSample development by creating an account on GitHub.

生成手順

対象プロジェクトを右クリック→エクスポート

Javadoc選択

設定をしていき、完了をクリック

「次の可視性を持つメンバーのjavadocを生成」では、どのレベルでjavadocを生成するかを設定します。
説明については選択するとEclipseはすぐ下に出てくるのでそこを見ましょう。

「標準ドックレットを使用」の「宛先」で、javadocの出力先を指定します。
デフォルトではsrcと同じ階層にdocというディレクトリを作成し、
そこへ出力します。

ここでオプションを設定します。お好きにどーぞ。

追加のjavadocオプションで文字コードなどを指定し、
完了まで押すと、宛先で指定していたところにjavadocが生成されています。

ここでのオプションは、コマンドなどでjavadocを作成するときのオプションと同等です。

この中のindex.htmlをブラウザで開くと、始めに紹介した画面へと遷移します。

このようにjavadocコメントを書くかどうかで
コードの読みやすさは全然違います。

javadcコメントは必須で書きましょう！！

また、javadocコメントにはさまざまな種類があります。

よければこちらの記事もご覧ください。

【Java】よく使うjavadocタグ一覧とサンプル

javadocタグの種類と使用方法を説明していきます。

参考サイト

javadocコマンド