※私は転職で年収72万upしました。
今回はJavaでプログラム仕様書を作成する際に用いられるjavadocの使い方について紹介します。javadocを使用して、作成された仕様書は以下のようになります。
基本的なコマンドとオプション
まずはjavadocコマンドとそのオプションについて確認しましょう。
[基本形]
command $ javadoc [オプション] ソースファイル
クラス内にあるprivateで指定されたフィールドはプログラム仕様書に出力されません。出力させるためには[-private]オプションを使用します。
command $ javadoc -private ソースファイル
プログラム仕様書を指定したフォルダ内に作成させるには[-d]オプションを使用します。
command $ javadoc -d /Users/key/Desktop/Java_Practice ソースファイル
ロケールやエンコーディングを指定する場合には[-locale]や[-encoding]オプションを使用します。
javadocのオプションを確認したい場合は以下で全てのオプションを確認できます。（ぜひ一度確認してみてください）
command $ javadoc -help
使用方法:
javadoc [options] [packagenames] [sourcefiles] [@files]
オプションは次のとおりです:
--add-modules <module>(,<module>)*
初期モジュールに加えて解決するルート・モジュール、または
<module>がALL-MODULE-PATHである場合はモジュール・パスの
すべてのモジュール。
-bootclasspath <path>
非モジュラ・リリースで使用されるプラットフォーム・クラス・ファイル
の場所をオーバーライドする
-breakiterator
BreakIteratorで最初の文を計算する
--class-path <path>, -classpath <path>, -cp <path>
ユーザー・クラス・ファイルのある場所を指定する
-doclet <class>
代替docletを介して出力を生成する
-docletpath <path>
docletクラス・ファイルのある場所を指定する
--enable-preview
プレビュー言語機能を有効にする。-sourceまたは--releaseとともに
使用されます。
-encoding <name>
ソース・ファイルのエンコーディング名
-exclude <pkglist>
除外するパッケージ・リストを指定する
--expand-requires <value>
ドキュメント化するモジュールのセットを拡張するための
ツールを指定する。デフォルトでは、コマンドラインで明示的に
指定されたモジュールのみがドキュメント化されます。"transitive"の値は、
それらのモジュールのすべての"requires transitive"依存性を追加で
含めます。"all"の値は、それらのモジュールのすべての依存性を
含めます。
-extdirs <dirlist>
インストール済み拡張機能の位置をオーバーライドする
--help, -help, -?, -h
コマンドライン・オプションを表示して終了する
--help-extra, -X
非標準オプションの概要を出力し終了する
-J<flag> <flag>を実行システムに直接渡す
--limit-modules <module>(,<module>)*
参照可能なモジュールの領域を制限します
-locale <name>
en_USやen_US_WINなどの使用するロケール
--module <module>(,<module>)*
指定されたモジュールをドキュメント化する
--module-path <path>, -p <path>
アプリケーション・モジュールを検索する位置を指定する
--module-source-path <path>
複数モジュールの入力ソース・ファイルを検索する位置を指定する
-package
package/protected/publicタイプとメンバーを表示します。名前のある
モジュールの場合、すべてのパッケージとすべてのモジュール詳細を表示します。
-private
すべてのタイプとメンバーを表示します。名前のあるモジュールの場合、
すべてのパッケージとすべてのモジュール詳細を表示します。
-protected
protected/publicタイプとメンバー(デフォルト)を表示します。名前のある
モジュールの場合、エクスポートされたパッケージとモジュールのAPIを表示します。
-public
publicタイプとメンバーのみを表示します。名前のあるモジュールの場合、
エクスポートされたパッケージとモジュールのAPIを表示します。
-quiet 状態メッセージを表示しない
--release <release>
指定されたリリースとソースの互換性を保つ
--show-members <value>
値が"public"、"protected"、"package"または"private"のいずれかの
どのメンバー(フィールドやメソッドなど)をドキュメント化するかを指定する。
デフォルトは"protected"で、publicおよびprotectedメンバーが表示され、
"public"ではpublicメンバーのみが表示されます。"package"では
public、protectedおよびpackageメンバーが表示され、"private"
ではすべてのメンバーが表示されます。
--show-module-contents <value>
モジュール宣言のドキュメント化の粒度を指定する。
使用可能な値は、"api"または"all"です。
--show-packages <value>
どのモジュールのパッケージをドキュメント化するかを指定する。使用可能な
値は、"exported"または"all"パッケージです。
--show-types <value>
値が"public"、"protected"、"package"または"private"のいずれかの
どの型(クラスやインタフェースなど)をドキュメント化するかを指定する。
デフォルトは"protected"で、publicおよびprotected型が表示され、
"public"ではpublic型のみが表示されます。"package"では
public、protectedおよびpackage型が表示され、"private"
ではすべての型が表示されます。
-source <release>
指定されたリリースとソースの互換性を保つ
--source-path <path>, -sourcepath <path>
ソース・ファイルのある場所を指定する
-subpackages <subpkglist>
再帰的にロードするサブパッケージを指定する
--system <jdk>
モジュラ・リリースで使用されるシステム・モジュールの場所をオーバーライドする
--upgrade-module-path <path>
アップグレード可能なモジュールの位置をオーバーライドする
-verbose Javadocの動作についてメッセージを出力する
--version バージョン情報を出力する
Standard docletにより提供されるもの:
--add-stylesheet <file>
生成されたドキュメントの追加スタイルシート・ファイル
--allow-script-in-comments
オプションおよびコメントでJavaScriptを許可します
-author @authorパラグラフを含めます
-bottom <html-code>
各ページに下部テキストを含めます
-charset <charset>
生成されるドキュメントのクロスプラットフォームでの文字セット
-d <directory>
出力ファイルの転送先ディレクトリ
-docencoding <name>
出力の文字エンコーディングを指定します
-docfilessubdirs
doc-fileサブディレクトリを再帰的にコピーします
-doctitle <html-code>
概要ページにタイトルを含めます
-excludedocfilessubdir <name>:..
指定された名前のdoc-filesサブディレクトリをすべて除外します
-footer <html-code>
各ページにフッター・テキストを含めます
--frames 生成された出力でフレームの使用を有効にします
-group <name> <g1>:<g2>...
指定する要素を概要ページにおいてグループ化します
-header <html-code>
各ページにヘッダー・テキストを含めます
-helpfile <file>
ヘルプ・リンクのリンク先ファイルを含めます
-html4 HTML 4.01出力を生成します
-html5 HTML 5出力を生成します
--javafx, -javafx
JavaFX機能を有効にします
-keywords HTMLのmetaタグに、パッケージ、クラスおよびメンバーの情報を含めます
-link <url> <url>にjavadoc出力へのリンクを作成します
-linkoffline <url1> <url2>
<url2>にあるパッケージ・リストを使用して<url1>のdocsにリンクします
-linksource HTML形式でソースを生成します
--main-stylesheet <file>, -stylesheetfile <file>
生成されたドキュメントのスタイル変更用ファイル
-nocomment 記述およびタグを抑制して宣言のみを生成します
-nodeprecated
@deprecated情報を除外します
-nodeprecatedlist
非推奨のリストを生成しません
--no-frames 生成された出力でフレームの使用を無効にします(デフォルト)
-nohelp ヘルプ・リンクを生成しません
-noindex 索引を生成しません
-nonavbar ナビゲーション・バーを生成しません
-noqualifier <name1>:<name2>:..
出力から修飾子のリストを除外します
-nosince @since情報を除外します
-notimestamp 非表示のタイムスタンプを除外します
-notree クラス階層を生成しません
--override-methods (詳細|要約)
オーバーライドされたメソッドを詳細または要約セクションでドキュメント化します
-overview <file>
HTMLファイルから概要ドキュメントを読み込みます
-serialwarn @serialタグに関する警告を生成しません
-sourcetab <tab length>
ソース内のタブの空白文字の数を指定します
-splitindex 1字ごとに1ファイルに索引を分割します
-tag <name>:<locations>:<header>
単一の引数を持つカスタム・タグを指定します
-taglet タグレットの完全修飾名を登録します
-tagletpath タグレットのパス
-top <html-code>
各ページに上部テキストを含めます
-use クラスとパッケージの使用ページを作成します
-version @versionパラグラフを含めます
-windowtitle <text>
ドキュメント用のブラウザ・ウィンドウ・タイトル
GNUスタイル・オプションでは、オプションの名前とその値を区切るために空白ではなく=を
使用できます。
command $ プログラム仕様書に詳細な解説を出力する
プログラム仕様書に詳細な解説を出力させるには、プログラム内の対象箇所を[ /** */ ]で囲みます。※javadocタグ（＠〜）についてはこのあと紹介します。
/**
* Heroクラス
* @author キー
* @version 1.0
*/
public class Hero {
・・・・処理・・・・
}javadocタグの利用
プログラム仕様書にメソッドのパラメータや戻り値の記述などを含める場合にはjavadcoタグを使用します。
[主なjavadocタグ]
| コメントの形式 | 意味 | 利用可能な場所 | ||
| class or interface | field | method | ||
| @author 作者名 | クラスの作者名 | ◯ | – | – |
| @version バージョン | バージョン情報 | ◯ | – | – |
| @param 引数名 解説 | 引数とその解説 | – | – | ◯ |
| @return 解説 | 戻り値の解説 | – | – | ◯ |
| @exception FQCN 解説 | 出力する可能性がある例外 | – | – | ◯ |
| @see クラス名 | 参考にしてほしいほかのクラス | ◯ | ◯ | ◯ |
| @since バージョン | 実装されたバージョン | ◯ | ◯ | ◯ |
| @deprecated 解説 | 非推奨として表示する場合に使う | ◯ | ◯ | ◯ |
※「スッキリわかるJava入門|実践編（第2版）」より引用
javadocの作成
では実際に紹介したjavadocタグを使用し、プログラム仕様書を作成していきます。
プログラム仕様書を作成する対象のソースファイルは2ファイルとしています。
[Mainクラス]
public class Main {
public static void main(String[] args) {
Hero h = new Hero();
Hero hero =h.status("バットマン",100,70);
System.out.println("ヒーローのステータスを表示");
System.out.println("名前：" + hero.getName());
System.out.println("HP：" + hero.getHp());
System.out.println("MP：" + hero.getMp());
}
}
[Heroクラス]
public class Hero {
private String name;
private int hp;
private int mp;
public String getName() {
return this.name;
};
public void setName(String name) {
this.name = name;
};
public int getHp() {
return this.hp;
}
public void setHp(int hp) {
this.hp = hp;
}
public int getMp() {
return this.mp;
}
public void setMp(int mp) {
this.mp = mp;
}
public Hero status(String name, int hp, int mp){
Hero hero = new Hero();
hero.setName(name);
hero.setHp(hp);
hero.setMp(mp);
return hero;
}
}
実行すると以下のようにコンソールに表示されます。
名前：バットマン
HP：100
MP：70
ではまず初めにjavadocタグを使用して、プログラム仕様書に出力する解説文を作成していきます。
[Mainクラス]
/**
* Mainクラス（ヒーローの情報をコンソールに出力させる）
* @author キー
* @see Hero
*/
public class Main {
public static void main(String[] args) {
Hero h = new Hero();
Hero hero =h.status("バットマン",100,70);
System.out.println("ヒーローのステータスを表示");
System.out.println("名前：" + hero.getName());
System.out.println("HP：" + hero.getHp());
System.out.println("MP：" + hero.getMp());
}
}
[Heroクラス]
/**
* Heroクラス
* @author キー
* @version 1.0
*/
public class Hero {
private String name;
private int hp;
private int mp;
public String getName() {
return this.name;
};
public void setName(String name) {
this.name = name;
};
public int getHp() {
return this.hp;
}
public void setHp(int hp) {
this.hp = hp;
}
public int getMp() {
return this.mp;
}
public void setMp(int mp) {
this.mp = mp;
}
/**
* ヒーローの情報を格納するクラス
* @param name ヒーローの名前
* @param hp ヒーローのHP
* @param mp ヒーローのMP
* @return 格納されたヒーローの情報
*/
public Hero status(String name, int hp, int mp){
Hero hero = new Hero();
hero.setName(name);
hero.setHp(hp);
hero.setMp(mp);
return hero;
}
}
ではjavadocコマンドを使用してプログラム仕様書を作成していきます。（今回はMacのターミナルで実行しています）
javadocディレクトリを作成し、そこにプログラム仕様書を作成するようにします。
command $ pwd
/Users/key/Desktop/Java_Practice/src
command $ ls
Hero.java Main.java javadoc
command $
以下を実行します。
command $ javadoc -private -d /Users/key/Desktop/Java_Practice/src/javadoc/ Main.java Hero.java
ソース・ファイルMain.javaを読み込んでいます...
ソース・ファイルHero.javaを読み込んでいます...
Javadoc情報を構築しています...
標準Docletバージョン11.0.13
全パッケージとクラスの階層ツリーを作成しています...
/Users/key/Desktop/Java_Practice/src/javadoc/Hero.htmlの生成中...
/Users/key/Desktop/Java_Practice/src/javadoc/Main.htmlの生成中...
/Users/key/Desktop/Java_Practice/src/javadoc/package-summary.htmlの生成中...
/Users/key/Desktop/Java_Practice/src/javadoc/package-tree.htmlの生成中...
/Users/key/Desktop/Java_Practice/src/javadoc/constant-values.htmlの生成中...
全パッケージとクラスのインデックスを作成しています...
/Users/key/Desktop/Java_Practice/src/javadoc/overview-tree.htmlの生成中...
/Users/key/Desktop/Java_Practice/src/javadoc/index-all.htmlの生成中...
全クラスのインデックスを作成しています...
/Users/key/Desktop/Java_Practice/src/javadoc/allclasses-index.htmlの生成中...
/Users/key/Desktop/Java_Practice/src/javadoc/allpackages-index.htmlの生成中...
/Users/key/Desktop/Java_Practice/src/javadoc/deprecated-list.htmlの生成中...
全クラスのインデックスを作成しています...
/Users/key/Desktop/Java_Practice/src/javadoc/allclasses.htmlの生成中...
/Users/key/Desktop/Java_Practice/src/javadoc/allclasses.htmlの生成中...
/Users/key/Desktop/Java_Practice/src/javadoc/index.htmlの生成中...
/Users/key/Desktop/Java_Practice/src/javadoc/help-doc.htmlの生成中...
command $
javadocディレクトリ内を確認
command $ cd javadoc
command $ ls
Hero.html index-all.html package-tree.html
Main.html index.html resources
allclasses-index.html jquery script.js
allclasses.html member-search-index.js search.js
allpackages-index.html member-search-index.zip stylesheet.css
constant-values.html overview-tree.html type-search-index.js
deprecated-list.html package-search-index.js type-search-index.zip
element-list package-search-index.zip
help-doc.html package-summary.html
command $様々なファイルが作成されています。
対象クラスのプログラム仕様書を確認
Main.java | Hero.java のプログラム仕様書はそれぞれ「Main.html」と「Hero.html」になります。これらをブラウザに貼り付けると以下のようにjavadocで作成されたプログラム仕様書が確認できます。
しっかりとそれぞれのプログラム仕様書が作成されていることが確認できました。今回はjavadocを使用して、Javaのプログラム仕様書を作成する方法について確認していきました。
[オススメ記事]
コメント