javadocタグの種類と使用方法について解説！！

javadocタグとは、javadocコメントで使用される
アノテーションです。

javadocコメントとは何かを知りたい方は、
先にこちらの記事をお読みください。

【Java】Javadocコメントとは？使用例あり

JavadocコメントはJavaで開発しているのなら必須で使用するコメントです。必ず身につけておきたい知識。今回はその使用方法をメインにご説明していきます。

今回は、javadocタグの中でも、
よく使うタグの種類とその使い方を
タグごとに説明していこうと思います。

タグ一覧
あとがき

タグ一覧

タグ	意味	サンプル
@author	作成者	@author Takumi
@return	戻り値の説明	@return HelloWorldの文字列
@throws	例外	@throws NullPointerException
@see	関連項目	@see <a href=”https://tsuka-ma.com/javadoctag/“>javadocタグ一覧</a>
{@link}	参照先のリンク	{@link HelloWorld#SetHelloWorld()}
{@literal}	そのままの文字を表示	{@literal a < b}の”<“などのjavadoc内で認識されない文字を書くとき
{@code}	<code>{@literal}</code>	{@code List<String>}などコードを書きたいとき

@author

作成者情報です。

意外と重要です。

サンプルコード

package com.example.demo;

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

/**
 * @author Takumi
 *
 */
@SpringBootApplication
public class HelloWorldApplication {

	public static void main(String[] args) {
		SpringApplication.run(HelloWorldApplication.class, args);
		
		System.out.println("Hello World!!");
	}
}

表示例

現場では、他人の書いたコードを修正する場合が多々あります。

その際に、作成者が誰なのかが書いてあるか、書いていないかで
効率が少し違います。

書いてない場合は、
わからないコードが出てきた時に、

「あーわからん。。。誰だこのコード書いたの。」
タスク一覧などで調べる。。。
「ああ、あの人か。スラック飛ばそ。」

と、一手間増えてしまいます。

逆に、作成者情報がコードに書いてあれば一瞬ですね。

このタグは、クラスだけではなく、
メソッドにもつけられるので、
修正でメソッドのみを作成したとかでも使えますね。

@return

返り値の説明です。

型だけだったらデフォルトで表示されるのですが、
その値がどんな値なのかの説明があると、なお分かりやすいです。

サンプルコード

package com.example.demo;

public class HelloWorld {

	/**
	 * @return "HelloWorld"を返す。
	 */
	public String SetHelloWorld(){

		String helloWorld = "";

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

		return helloWorld;
	}
}

表示例

これがつけてあるか無いかで、
メソッドの中まで見に行く手間が省けます。

コードなんで結局、
結果が知れればいいわけですから。

書かれてない場合は、
F3でメソッドの中まで潜って、
コードを読むという手間が出てきます。

非常に効率が悪くなります。

ITを扱っているんですから、
効率にはこだわっていきましょう。

@throws

どの例外が発生する場合があるかの説明です。

なおかつ、どういった場合に発生するのかも記載できます。

サンプルコード

package com.example.demo;

public class NumberFormatExceptionSample {

	/**
	 * @param scoreStr
	 * @return 引数の文字列方の数値をintに変換し、２倍にして返す
	 * @throws NumberFormatException 文字列が数値でない場合に発生
	 */
	public int GetDoubleScore(String scoreStr) throws NumberFormatException{
		
		try {
			
			Integer score = Integer.parseInt(scoreStr);
			
			return score.intValue() * 2;
		
		} catch (NumberFormatException e) {
			
			System.err.println(e.getMessage());
			e.printStackTrace();
			
			throw e;
		}
	}
	
}

表示例

引数でString型の数値を受け取って、
それをintに変換し、尚且つ２倍にして返すコードの例です。

こういった型の変換では、よくエラーが起きます。

そのため、@throwsをつけて例外を明示しておけば、
コードの修正をする際に、ハンドリングがしやすいですし、
解析する際にも、どのメソッドで例外が投げられているのかが
分かりやすいです。

コードは、バグやエラーが発生した際に、
素早く、どこで起こったかがわかるように
書くべきです。

そうしておくことで、
無駄な残業は減るでしょう。

@throwsはその少しの助けとなります。

@see

@link

文章中に、参考サイトや関連メソッド、変数などを埋め込むことが
できます。

メソッドAとメソッドBがあったとして、
メソッドAは、メソッドBを使用した後に使用する、や、
メソッド内で、特定のローカル変数を使用している場合に、
そのローカル変数を明示したい、
などの際に便利です。

サンプルコード

package com.example.demo;

public class LinkSample {

	/** 2 */
	private int i = 2;
	
	/**
	 * @param scoreStr 文字列型の数値
	 * @return 引数の文字列方の数値をintに変換し、{@link #i}倍にして返す
	 * @throws NumberFormatException 文字列が数値でない場合に発生
	 * @see #RoundingNumber(float)
	 */
	public int GetDoubleScore(String scoreStr) throws NumberFormatException{
		
		try {
			
			Integer score = Integer.parseInt(scoreStr);
			
			return score.intValue() * i;
		
		} catch (NumberFormatException e) {
			
			System.err.println(e.getMessage());
			e.printStackTrace();
			
			throw e;
		}
	}
	
	/**
	 * @param number 小数付きの数値
	 * @return 四捨五入された数
	 */
	public String RoundingNumber(float number) {
		
		int roundNumber = Math.round(number);
		
		return Integer.valueOf(roundNumber).toString();
	}
}

表示例

このように文章中に、リンクとしてメソッドやローカル変数を埋め込めます。

ちなみに、これをクリックすると、

このように、メソッドや変数の説明を見ることができます。

もし、文章中にメソッドや変数を用いる場合は、
たった{@link }で囲うだけなので、
使用すると、よりコードが見やすくなるでしょう。

@code

これに関しては、
説明するよりも、
@codeを用いて書いた場合と、
用いずに書いて場合の違いを見せた方が
わかりやすいと思います。

以下、@codeを用いた例と
用いなかった例をご覧ください。

@codeを用いたサンプル

サンプルコード

package com.example.demo;

import java.util.ArrayList;
import java.util.List;

public class CodeSample {

	/**
	 * @return {@code List<String>}型でHello World!!!を詰めるメソッド
	 * 
	 */
	public List<String> GetHelloWorldList() {
		
		var helloWorldList = new ArrayList<String>();
		
		helloWorldList.add("Hello ");
		helloWorldList.add("World");
		helloWorldList.add("!!!");
		
		return helloWorldList;
	}
	
	/**
	 * @param helloWorldList 繋げるとHello World!!!となるStringの{@code List<String>}
	 * @return Hello World!!!
	 */
	public String RoundingNumber(List<String> helloWorldList) {
		
		String helloWorld = "";
		for (String helloWorldStr : helloWorldList) {
		
			helloWorld += helloWorldStr;
		}
		
		return helloWorld;
	}
}

表示例

@codeを用いないサンプル

サンプルコード

package com.example.demo;

import java.util.ArrayList;
import java.util.List;

public class CodeSample {

	/**
	 * @return List<String>型でHello World!!!を詰めるメソッド
	 * 
	 */
	public List<String> GetHelloWorldList() {
		
		var helloWorldList = new ArrayList<String>();
		
		helloWorldList.add("Hello ");
		helloWorldList.add("World");
		helloWorldList.add("!!!");
		
		return helloWorldList;
	}
	
	/**
	 * @param helloWorldList 繋げるとHello World!!!となるStringのList<String>
	 * @return Hello World!!!
	 */
	public String RoundingNumber(List<String> helloWorldList) {
		
		String helloWorld = "";
		for (String helloWorldStr : helloWorldList) {
		
			helloWorld += helloWorldStr;
		}
		
		return helloWorld;
	}
}

表示例