前回、Javadocについてを簡単にですがまとめました。
軽く復習すると、
・Javadocとは、クラスやメソッドを利用する人向けのドキュメントであること
・クラスや『メンバー』（フィールドとメソッドをまとめてこう呼ぶ）に対しての説明を書く場合にのみ使用すること
・Javadocからクラスやメソッドの仕様などが読み取れること
などを学びました。
今回は実際にブラウザでJavadocを確認したり、読み取りを行いたいと思います。
■標準APIのJavadocの確認方法
Javaでアプリ開発をする中で、一番確認するJavadocは恐らく標準APIのJavadocと書籍にありました。
標準APIのJavadocは「クラス名 javadoc」と検索すると、
古いバージョンがヒットすることも多いで、ブックマークとして以下に貼り付けておきます。
・Java SE 日本語ドキュメント（バージョンごと）
https://www.oracle.com/jp/java/technologies/documentation.html
確認したいバージョンの「日本語」のリンクをクリックすると、バージョン個別のトップページに遷移します。
・JDK 17ドキュメント
https://docs.oracle.com/javase/jp/17/index.html
先ほどのページで確認したいバージョン(例えば、17)の「日本語」をクリックした遷移先のページです。
様々なリンクがありますが、左側のナビゲーションメニューから「APIドキュメント」をクリックするとJavadocを開くことができます。
・JDK 17 Javadocのトップページ
https://docs.oracle.com/javase/jp/17/docs/api/index.html
■Javadocの着目すべき点
JDK 17 Javadocのトップページへ行くと情報量が非常に多くどこを読めばいいかわかりません。
ここで着目すべき点はクラスとメソッドの説明です。
■例：「Listインターフェース」の「addメソッド」を呼び出す際に引数にnullを渡しても良いのかを確認する
確認手順は以下の通りです。
①まず、「Listインターフェース」のJavadocを確認します。
今回探したいListインターフェースは正確には「java.util.List」になります。
java.utilパッケージのListクラスという意味です。
この「java.util.List」を以下のページ内右上の検索フィールドに入力しエンターを押します。
https://docs.oracle.com/javase/jp/17/docs/api/index.html
これで「Listインターフェース」のJavadocが表示されました。
②クラスやインターフェースのJavadocの先頭で3つを確認する
クラスやインターフェースのJavadocの先頭で特に注目するのは以下3点です。
★継承関係
スーパークラスやサブクラスを確認することで、どのクラス/インターフェースにキャストができるのか、
どの型の変数や引数に渡すことができるのかを確認できます。
今回ですと、すべてのスーパー・インターフェース/「Collection<E>」,「 Iterable<E>」とあります。
ここから、Iterableインターフェース ➡継承➡ Collectionインターフェース ➡継承➡ Listインターフェース
となっていることが分かります。要はListインターフェースの全親インターフェースがわかるということです。
https://workteria.forward-soft.co.jp/blog/detail/10082#anchor_1
★実装インターフェース
実装しているインターフェースを見ることで、そのクラス（インターフェース）がどのような役割を持っているのかを確認することができます。
Listインターフェースの場合は「既知のすべての実装クラス:」が表示されています。
例えば、「ArrayList」などがどのような役割を持つのかをクリックし確認することができます。
また、その下には「public interface List<E> extends Collection<E>」から始まるところから
このクラスについての説明があります。
★導入されたバージョン
今回はJava 17ですが、プロジェクトの環境によってはJava 8やJava 11など古いバージョンを使うことも多くあります。
見ているクラスやメソッドが、使っているJavaバージョンで利用可能なのかを確認する必要があります。
③addメソッドの説明を見る
先ほどの導入されたバージョンから下にスクロールを進めると「メソッドの詳細」の箇所に到達します。
そこにaddメソッドの説明が記載されています。
早速見てみると「例外」の項には、addメソッドで投げられる可能性のある例外が記述されています。
例外：「NullPointerException - 指定された要素がnullで、このリストがnull要素を許可しない場合」
※nullとは、変数がどこも参照していないことを示す値です。要は空です。
変数がどこも参照していないのに、参照先のメソッドを呼び出そうとすると、
"NullPointerException"が発生します。
上記の情報からListインターフェースの仕様として、addメソッドにnullを渡した場合、
実装クラスによっては例外である”NullPointerException”が投げられる可能性があることが分かりました。
では、Listの実装で良く使うArrayListはどうなっているのかを確認してみます。
Java.util.Listと同様java.util.ArrayListのJavadocを開き、addメソッドの欄までスクロールします。
https://docs.oracle.com/javase/jp/8/docs/api/java/util/ArrayList.html
ArrayListのaddメソッドのJavadocには例外を投げるケースが記載されていません。
ここから、ArrayListはnullを許容する実装であり、addメソッドにnullを渡しても
例外”NullPointerException”は投げられないことがわかりました。
なお、ArrayListクラス自体の説明序盤でもnullを許容する実装であることが明記されています。
以下抜粋：
Listインタフェースのサイズ変更可能な配列の実装です。
リストのオプションの操作をすべて実装し、nullを含むすべての要素を許容します。
※ここまでは日本語版Javadocを見てきましたが、日本語場はあくまで参考用の為、
機械翻訳した上で適宜人間が修正を加えたものになります。
英語に抵抗があってもゆくゆくは英語版を読めるのが好ましいとの事です。
また、Oracle社による日本語版の標準APIのJavadocでは、文章にマウスカーソルを重ねると英語の原文を表示することができます。
がしかし、先ほどやってみましたができませんでした。後で調べます。
ちなみに、「すべてのスーパー・インターフェース」の上には、「型パラメータ:」の記載があります。
（型パラメータは"型変数"や"仮型パラメータ"などとも呼ばれているようです。）
ここには「指定する型などの情報」が記載されています。
なぜこんな曖昧な表記の仕方なのかいうと、インターフェースを作成する際など、具体的な型などが決まっていないからです。
そのような時に、型パラメータが使用されるというわけです。
ただListでは<E>となっていますが、なんでもいいわけではなく決まりがあります。
例えば、<E>はElementの頭文字で「要素」を表しています。
なので、Listインタフェースでは、「E - このリスト内に存在する要素の型」との記載があるわけです。
List内の要素が文字列であればStringとなり、以下のように使用します。
List<String> obj = new ArrayList<String>();
注意点としては、型変数<E>に指定できるのは参照型のみで、基本型は使えません。
List<int>とは書けず、ラッパークラスを使用してList<Integer>とする必要があります。
参考：https://programmer-life.work/java/generics-type
https://so-zou.jp/software/tech/programming/java/generic/#:~:text=%E5%9E%8B%E5%A4%89%E6%95%B0%20(type%20variable)%E3%80%8C,%E5%90%8D%E5%89%8D%E3%81%8C%E4%BD%BF%E7%94%A8%E3%81%95%E3%82%8C%E3%81%BE%E3%81%99%E3%80%82
■IntelliJ IDEAからJavadocを見る
IDEを使っていればブラウザを開かなくてもJavadocを確認できます。
確認したいクラス名やメソッド名テキストカーソルを合わせた状態で、
[Ctrl]+[Q]を押すとエディタ内のポップアップウィンドウでJavadocを表示できます。
もう一度[Ctrl]+[Q]を押すとドキュメントツールウィンドウが現れ、
テキストカーソル位置のJavadocを常時自動的に表示してくれるようになります。
慣れないAPIやライブラリを利用するときに使用するといいです。
■EclipseからJavadocを見る
Eclipseの場合は対象クラスやメンバー（フィールドとメソッドをまとめた呼び方）の名前をcursor hoverすると表示されます。
「@author」など色んな注釈が用意されており、Eclipseの場合、javadocコメント内でctrl+spaceで一覧が表示されます。
アノテーションについては次回まとめます。
これでJavadocから必要な情報を読み取れるようになりました。
次回は実際にJavadocを書くことについてまとめます。