|
| |
 |
javadoc編 |
 |
◆javadocとは? |
| javadocとはjavaのソースファイルからjavaのリファレンスマニュアルを生成してくれるコマンドです。ソースファイルに決まった形式でコメントを書いておくだけで簡単にリファレンスマニュアルができてしまいます。 |
| ◆ここでの環境 |
| OS |
Windows XP |
| J2SE SDK |
1.4.1_01 |
|
|
|
| ◆Javaの実行環境の構築 |
| javadocはJ2SE SDKに含まれているコマンドです。アプリケーション編を参考にJavaの実行環境を構築してください。 |
| ◆Javaソースファイルの作成 |
| テスト用のJavaソースファイルを作ってみたいと思います。コメントのところに注目してください。 |
| HelloWorldJavaDoc.java(ここからダウンロード) |
import java.io.*;
/**
* JavaDocテスト用クラスです。ソースに意味はありません。<br>
* @author 田中宏和
* @version 1.0
*/
public class HelloWorldJavaDoc {
/**
* コメント
*/
private String comment;
/**
* 引数なしのコンストラクタ
*/
public HelloWorldJavaDoc() {
}
/**
* コメントを引数とするコンストラクタ
* @param comment コメント
*/
public HelloWorldJavaDoc(String comment) {
this.comment = comment;
}
/**
* コメントの取得
* @return コメントを返す。<br>
* コメントが設定されていない場合「知らない」を返す。
*/
public String getComment() {
if (comment==null) {
return "知らない";
}
return comment;
}
/**
* コメントを設定
* @param comment コメント
*/
public void setComment(String comment) {
this.comment = comment;
}
/**
* コメントを出力ストリームに出力させる。<br>
* コメントがない場合「知らない」と出力。
* @param OutputStreamWriterクラス
* @throws java.io.IOException 入出力エラーが発生した場合にスローされる
*/
public void sayComment(OutputStreamWriter out) throws IOException {
if (comment==null) {
out.write("知らない");
} else {
out.write(comment);
}
}
} |
|
|
| コメントのところに@ではじまる文字列がありますね(赤字の部分)。docタグと呼ばれるもので後に説明を書きます。 |
| |
| ◆javadocコマンドを使ってJavaのリファレンスマニュアルの作成 |
| さっそくjavadocコマンドを使ってみたいと思います。ここでは-dというオプションをつけて出力する場所を指定しています。 |
| コマンドプロンプト |
| C:\>cd C:\JavaHello\javadoc
C:\JavaHello\javadoc>javadoc
-d docs HelloWorldJavaDoc.java
ソースファイル HelloWorldJavaDoc.java を読み込んでいます...
Javadoc 情報を構築しています...
標準 Doclet バージョン 1.4.1
docs\constant-values.html の生成
全パッケージとクラスの階層ツリーを作成しています...
全パッケージとクラスのインデックスを作成しています...
docs\overview-tree.html の生成
docs\index-all.html の生成
docs\deprecated-list.html の生成
全クラスのインデックスを作成しています...
docs\allclasses-frame.html の生成
docs\allclasses-noframe.html の生成
docs\index.html の生成
docs\packages.html の生成
docs\HelloWorldJavaDoc.html の生成
docs\package-list の生成
docs\help-doc.html の生成
docs\stylesheet.css の生成
C:\JavaHello\javadoc>
|
|
| おおお!うまくいったみたいです。docsフォルダの中に生成されているので見てみましょう。index.htmlを開いてみてください。 |
 |
| おおおおお!リファレンスマニュアルができてるぞ! |
| → 作成したJavaリファレンスマニュアル |
| |
| ◆docタグの説明 |
| ■すべての場所で使用可能なタグ |
| タグの記述方法 |
説明 |
| @see 関連項目 |
関連項目を記述します。
(例1) テキストを記述
@see "The Java Programming Language"
(例2) URLを記述
@see <a href="spec.html#section">Java
Spec</a>
(例3) クラス名、メソッド名、変数名を記述
@see #FIELD_NAME
@see #method(int , String)
@see java.lang.String
@see java.lang.String#equals(Object) |
@deprecated コメント
|
この API は (動作はするが) 使用すべきでないことを示すコメントを追加します。クラスにdeprecatedタグを使用するとすべてのフィールド、メソッドにコメントが表示されます。
(例)
@deprecated このクラスは○○に置き換わりました。
@deprecated ○○メソッドを使用してください。 |
| @since 導入されたバージョン |
導入されたバージョンを記述します。
(例)
@since 1.3 |
| {@link クラス名#メンバ名 表示テキスト} |
リンクを挿入します。
(例)
{@link #myMethod(int , int) myMethod} メソッドを使ってください。 |
|
| ■クラスおよびインターフェースのコメントに記述するタグ |
| タグの記述方法 |
説明 |
| @author 著作者 |
著作者を記述します。-authorオプションをつけるとドキュメントに表示されます。
(例)
@author Hirokazu Tanaka |
| @version バージョン |
バージョンを記述します。-versionオプションをつけるとドキュメントに表示されます。
(例)
@version 1.7 |
|
| ■メソッドのコメントに記述するタグ |
| タグの記述方法 |
説明 |
@param 引数名 説明
|
引数名とその引数の説明を記述します。
(例)
@param userName ユーザー名 |
@return 返り値の説明
|
返り値の説明を記述します。
(例)
@return データが存在する場合true、存在しない場合falseを返します。 |
@throws 例外クラス名 説明
(@exeption 例外クラス名 説明) |
スローされる可能性のある例外の名前とその説明を記述します。
(例)
@throws java.io.IOException 入出力エラーが発生した場合にスローされる。 |
|
| |
| ◆javadocコマンドの使用方法 |
使い方: javadoc [options] [packagenames] [sourcefiles] [classnames] [@files]
-overview <file> HTML ファイルから概要ドキュメントを読み込む
-public public クラスとメンバのみを示す
-protected protected/public クラスとメンバを示す (デフォルト)
-package package/protected/public クラスとメンバを示す
-private すべてのクラスとメンバを示す
-help コマンド行オプションを表示して終了する
-doclet <class> 代替 doclet を介して出力を生成する
-docletpath <path> doclet クラスファイルを探す場所を指定する
-sourcepath <pathlist> ソースファイルのある場所を指定する
-classpath <pathlist> ユーザクラスファイルのある場所を指定する
-exclude <pkglist> 除外するパッケージリストを指定する
-subpackages <subpkglist> 再帰的にロードするサブパッケージを指定する
-breakiterator BreakIterator で最初の文を計算する
-bootclasspath <pathlist> ブートストラップクラスローダによりロードされた
クラスファイルの位置をオーバーライドする
-source <release> 指定されたリリースとソースの互換性が提供される
-extdirs <dirlist> 拡張機能がインストールされた位置をオーバーライドする
-verbose Javadoc の動作についてメッセージを出力する
-locale <name> en_US や en_US_WIN などの使用するロケール
-encoding <name> ソースファイルのエンコーディング名
-J<flag> <flag> を実行システムに直接渡す
標準の doclet により提供されるもの:
-d <directory> 出力ファイルの転送先ディレクトリ
-use クラスとパッケージの使用ページを作成する
-version @version パラグラフを含める
-author @author パラグラフを含める
-docfilessubdirs doc-file サブディレクトリを再帰的にコピーする
-splitindex 1 字ごとに 1 ファイルに索引を分割する
-windowtitle <text> ドキュメント用のブラウザウィンドウタイトル
-doctitle <html-code> 概要ページにタイトルを含める
-header <html-code> 各ページにヘッダを含める
-footer <html-code> 各ページにフッタを含める
-bottom <html-code> 各ページに下部テキストを含める
-link <url> <url> に javadoc 出力へのリンクを作成する
-linkoffline <url> <url2> <url2> にあるパッケージリストを使用して <url>
の docs にリンクする
-excludedocfilessubdir <name1>:.. 指定された名前の doc-files サブディレクトリを
すべて除外する。
-group <name> <p1>:<p2>.. 概要ページにおいて指定するパッケージをグループ
化する
-nocomment 記述およびタグを抑制し、説明だけを生成する。
-nodeprecated @deprecated 情報を除外する
-noqualifier <name1>:<name2>:... 出力から修飾子のリストを除外する。
-nosince @since 情報を除外する
-nodeprecatedlist 非推奨 API のリストを生成しない
-notree クラス階層を生成しない
-noindex 索引を生成しない
-nohelp ヘルプリンクを生成しない
-nonavbar ナビゲーションバーを生成しない
-quiet 画面にステータスメッセージを表示しない
-serialwarn @serial タグに関する警告を生成する
-tag <name>:<locations>:<header> 単一の引数を持つカスタムタグを指定する
-taglet タグレットの完全修飾名を登録する
-tagletpath タグレットのパス
-charset <charset> 生成されるドキュメントの文字エンコーディング
-helpfile <file> ヘルプリンクのリンク先ファイルを含める
-linksource HTML 形式でソースを生成する
-stylesheetfile <path> 生成されたドキュメントのスタイル変更用ファイル
-docencoding <name> 出力エンコーディング名 |
|
| ◆javadocコマンドの使用例 |
| (例1) ファイル名を指定 |
javadoc Test.java
javadoc Test1.java Test2.java
javadoc *.java
javadoc C:\java\mysrc\Test1.java |
| (例2) 出力するディレクトリを指定 |
javadoc -d mydocs Test.java
javadoc -d C:\java\mydocs Test.java |
| (例3) パッケージを指定 |
| javadoc -d mydocs -sourcepath C:\java\mysrc com.hellohiro.mypackage1
com.hellohiro.mypackage2 |
| |
| (参考URL) |
| http://java.sun.com/j2se/1.3/ja/docs/ja/tooldocs/javadoc/ |
■書籍
Java関連の書籍 |
|
| |
|
| |
| ツールの部屋
- Java関連の書籍 - デザインパターン - 情報交換掲示板
- HOME |