javaのソースファイルの内容を解釈してリファレンスマニュアルを生成してくる便利なコマンド。この存在を知らずに手書きでレファレンスを書いた後にjavadocの存在を知ると本気で泣ける(経験者談)
JDKがインストール済みならばすでにインストールされています。JDKインストールフォルダのbinフォルダ内に実行ファイルがあるはずです。
JDKすらインストールしていないという人はまずはSUNのWEBページからJDKを落としてインストールしてください。
また、インストールはしてあるものの環境設定をJBuilderやその他の統合開発環境に依存している人はPATHを指定して下さい。このページではプロンプトからjavadocを使うことを想定しています。Windows9x系ならばシステムドライブのルートにあるautoexec.batを編集して、Windows2000ではコンパネの「システム」-「詳細」-「環境変数」から設定できます。
書式は・・・すでにシステムがいくつかパスを指定してあると思うのでその最後にjdkのbinフォルダの絶対パスをセミコロンで区切って追加して下さいな。
javadocはふつうに書いたjavaのソースファイルに対しても動作させることができますが何も手を加えていないと、メソッドとフィールドが淡々と並べられているだけのリファレンスになってしまいます。
コメントや引数の解説などをするのにはjavadoc用の一定の書式に従ってソースファイルを書かなくてはいけません。
って、訳でソースファイルの書き方の説明。
コメント
クラス名、フィールド変数、メソッド定義の直前に記述します。
必ず/**で始まり*/で終わるようにします。また、行はじめの*は無視されます。
コメントの中にhtmlタグをそのまま記述することができます。ただし、<H1><H2>タグは使用できないので注意。
コメントの書き始めからビリオド+空白あるいはピリオド+改行あるいはタグで区切られるまでを最初の1文と認識して、メソッド一覧の「1行コメント」に書き込まれます。
ピリオドを目印にしているので日本語入力の際は気をつけて下さいな。
タグ
javadocが独自に定義するタグがいくつか存在します。@で始まります。コメントの中に書くことになりますが、同じタグを何個も使う場合(たとえば引数が複数個ある場合)は同じタグは連続した行にかかれなければいけません。
次にタグの一覧を載せます。タグの種類、説明、使える場面を書きます。使える場面はクラス、インターフェース、フィールド、コンストラクタ、メソッドで使える場面の頭文字だけを記述してあります。
タグの書式 説明 使用場面 @author 著者名 著者名を記述。複数可。ただし、javadocのオプション-authorをつけなければ示されません。 ク、イ @version バージョン バージョン情報を記述。複数不可。ただし、javadocのオプション-versionをつけなければ表示されません。 ク、イ @see クラス名 「See also」でリンクするクラス名を記述。また「"」でくくるとリンクが張られません。メソッドやフィールドまで指定したい場合はクラス名#に続いて入力。 ク、イ、フィ、コ、メ @since バージョン どのバージョンから存在しているのかを示します。 ク、イ、フィ、コ、メ @deprecated コメント 置き換わったAPIを記述する。廃止の場合は「No replacement」。 ク、イ、フィ、コ、メ @param 引数名 説明 引数とその説明。 コ、メ @return 説明 返値の説明。 メ @exception 絶対クラス名 説明 例外の説明。 コ、メ
例
/** * 入力変換クラスを表すインターフェースです。. * * @version 1.0, 03 May, 2002 * @author Mutuki */ public interface Converter{ /** * 扱うDictionaryを変更するメソッド。 * @param dic 変更したいDictionaryクラスのインスタンス。 */ public void changeDictionary(Dictionary dic); /** * 新たに入力を受け付け、その入力をこれまでの入力と合わせて新たな変換済み * 文字列を返すメソッド。. * @param chr 追加したいString * @return 変換済み文字列。 */ public String put(String chr); /** * 新たに入力を受け付け、その入力をこれまでの入力と合わせて新たな変換済み * 文字列を返メソッド。. * @param chr 追加したいcharacter * @return 変換済み文字列。 */ public String put(char chr); /** * バックスペースの動作を行うメソッド。 * @return バックスペース適用済み文字列。 */ public String remove(); /** * 内部状態を全て消去して初期状態に戻すメソッド。. ただし、Dictionaryを * インスタンス精製時のものに戻すことはない。 */ public void resetAll(); /** * これまでに入力した文字列を全てローマ字で返すメソッド。 * @return 入力済み文字列 */ public String showEnteredStr(); }
まずはヘルプ
コマンドプロンプトから、引数を何も指定しないでjavadocコマンドを使用すると次のようなメッセージが表示されます。使い方に困ったときはまずはこのヘルプを読んでみるとよいでしょう。まあ、詳しい使い方はこの次で解説しますから、毎回このページにきてくださるのであればそれはそれで。
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 クラスファイルを探す場所を指定する -1.1 JDK 1.1 エミュレート doclet を使って出力を生成する -sourcepath <pathlist> ソースファイルのある場所を指定する -classpath <pathlist> ユーザクラスファイルのある場所を指定する -bootclasspath <pathlist> ブートストラップクラスローダによりロードされた クラスファイルの位置をオーバーライドする -extdirs <dirlist> 拡張機能がインストールされた位置をオーバーライドする -verbose Javadoc の動作についてメッセージを出力する -locale <name> en_US や en_US_WIN などの使用するロケール -encoding <name> ソースファイルのエンコーディング名 -J<flag> <flag> を実行システムに直接渡す 標準の doclet により提供されるもの: -d <directory> 出力ファイルの転送先ディレクトリ -use クラスとパッケージの使用ページを作成する -version @version パラグラフを含める -author @author パラグラフを含める -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 にリンクする -group <name> <p1>:<p2>.. 概要ページにおいて指定するパッケージをグループ化する -nodeprecated @deprecated 情報を除外する -nosince @since 情報を除外する -nodeprecatedlist 非推奨 API のリストを生成しない -notree クラス階層を生成しない -noindex 索引を生成しない -nohelp ヘルプリンクを生成しない -nonavbar ナビゲーションバーを生成しない -serialwarn @serial タグに関する警告を生成する -charset <charset> 生成されるドキュメントの文字エンコーディング -helpfile <file> ヘルプリンクのリンク先ファイルを含める -stylesheetfile <path> 生成されたドキュメントのスタイル変更用ファイル -docencoding <name> 出力エンコーディング名 エラー 1 個
javadocの書式。
javadoc ([options]* [packagenames]* [sourcefiles]* [classnames]*)|( [@files] )
です。って、これじゃ説明になっていませんね。正規表現と思いねえ。つまり*は0個でも良いし、何個指定してもかまわないわけだ。したがって、コマンドプロンプト上で無理をしようとすれば。
javadoc *.java
なんていう風にワイルドカードを使った無茶なやり方も可能です。
なんか小括弧と「|」で区切って[@files]だけ別扱いしていますが、これは後述。
オプション。
よく使うオプションについて解説。
オプション 説明 -d <directory> 生成するドキュメントを指定したディレクトリに保存します。何も指定しないとjavadocを起動したカレントディレクトリに作られてしまうので注意。私はよく「-d .\docs」と指定して、ソースファイルと、クラスファイル、ドキュメントファイルを分離しています。 -private このオプションを指定すると、ソースファイルに記述されているすべての要素がドキュメント化されます。このほかに、「-public」「-protected」がありますが、デフォルトでは「-public」が指定されています。 -sourcepath <pathlist> ソースファイルへのパスを指定します。これ以後、ソースファイルの指定にはパスを利用することができます。プログラムの作業場とコマンドプロンプトの起動位置が違うときなんかに便利。そのほか、-なんたらpathってのはそのなんたらの部分にパスを設定します。 -version
-authorそれぞれ、@versionと@authorを表示するようにします。デフォルトだと表示されません。せっかく書いたんだから表示しときましょう。 -windowtitle <text> これを指定しておかないと、index.htmlのタイトルが「生成されたドキュメント」になってかっこわるいです(汗 指定しておきましょう。 -link <url> これを指定すると、外にあるドキュメントを利用することができます。たとえば、ふつうにjavadocを使うとJavaAPIから継承した各種クラスやメソッドへのリンクは張られていませんがここで、SUNのページにある日本語ドキュメントのトップページのアドレスを指定しておけば、それらのリンクが張られるようになります。
そのほか、他人が作ったパッケージを利用している場合などにそのパッケージのドキュメントがすでに公開されていれば、そのドキュメントへのリンクを指定することによってドキュメント内でリンクをすることができます。
ただし、複数URLの指定ができないのでご注意。
@filesについて。
javadoc使うためには意外とオプションやなんやらを大量に書かないといけなくてめんどくさいですね。コマンドプロンプトでコマンド履歴が使えるのであれば別に良いのですが、わざわざ毎回直接入力しなくてはいけないときは面倒なことこの上ありません。
こういったときに、javadocに引き渡すオプションやソースファイルなどの情報を適当なテキストファイルに記述しておいて、
javadoc @ファイル名
と、すれば便利です。
ただし、この場合ワイルドカードによる指定ができないのでご注意。
ファイルの記述の仕方のサンプル。
-private -version -author -d .\docs -windowtitle ローマ字変換プログラム -link http://java.sun.com/j2se/1.3/ja/docs/ja/api/index.html test.java FepDebuger2.java fep