Manpages

名 前

javadoc − Java API ド キ ュ メ ン ト ジ ェ ネ レ ー タ

形 式

javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ −subpackages pkg1:pkg2:... ] [ @argfiles ]

パ ラ メ ー タ

引 数 の 順 序 は 任 意 で す 。

sourcefilenames

ス ペ ー ス で 区 切 ら れ た 一 連 の フ ァ イ ル 名 で す 。 パ ス 、 お よ び ア ス タ リ ス ク (*) な ど の ワ イ ル ド カ ー ド を 含 め る こ と が で き ま す 。 javadoc ツ ー ル が 処 理 す る の は 、 フ ァ イ ル 名 が 「 .java」 と い う 拡 張 子 で 終 わ り 、 そ の 拡 張 子 を 除 い た 名 前 が 実 際 に 有 効 な ク ラ ス 名 で あ る す べ て の フ ァ イ ル で す 。 し た が っ て 、 ハ イ フ ン を 含 む 名 前 (X-Buffer な ど ) や 、 そ の 他 の 無 効 な 文 字 を 含 む 名 前 を 付 け る こ と に よ っ て 、 そ れ ら の フ ァ イ ル を ド キ ュ メ ン ト 化 の 対 象 か ら 除 外 で き ま す 。 こ れ は 、 テ ス ト 用 の フ ァ イ ル や 、 テ ン プ レ ー ト か ら 生 成 さ れ た フ ァ イ ル の 場 合 に 便 利 で す 。 javadoc ツ ー ル は 、 ソ ー ス フ ァ イ ル 名 の 前 に 指 定 さ れ た パ ス を 使 用 し て 、 ソ ー ス フ ァ イ ル 名 を 探 し ま す 。 こ の 場 合 、 -sourcepath は 使 用 し ま せ ん 。 た と え ば 、 Button.java を 渡 す こ と は ./Button.java と 指 定 す る こ と と 同 じ で す 。 完 全 パ ス を 付 け た ソ ー ス フ ァ イ ル 名 の 例 は 「 /home/src/java/awt/Graphics*.java 」 の よ う に な り ま す 。 「 1 つ 以 上 の ク ラ ス の ド キ ュ メ ン ト 化 」 の 例 を 参 照 し て く だ さ い 。 ま た 、 「 パ ッ ケ ー ジ と ク ラ ス の ド キ ュ メ ン ト 化 」 の 例 の よ う に 、 パ ッ ケ ー ジ 名 と ソ ー ス フ ァ イ ル 名 を 組 み 合 わ せ る こ と も で き ま す 。

−subpackages pkg1:pkg2:...

指 定 さ れ た パ ッ ケ ー ジ 内 の ソ ー ス フ ァ イ ル か ら ド キ ュ メ ン ト を 生 成 し 、 再 帰 的 に サ ブ パ ッ ケ ー ジ を 処 理 し ま す 。 パ ッ ケ ー ジ 名 ま た は ソ ー ル フ ァ イ ル 名 を 指 定 す る た め の 代 替 手 段 で す 。

機 能 説 明

javadoc ツ ー ル は 、 一 連 の Java ソ ー ス フ ァ イ ル の 宣 言 お よ び ド キ ュ メ ン ト コ メ ン ト を 解 析 し 、 デ フ ォ ル ト で は public ク ラ ス と protected ク ラ ス 、 入 れ 子 ク ラ ス （ 匿 名 の 内 部 ク ラ ス を 除 く ） 、 イ ン タ フ ェ ー ス 、 コ ン ス ト ラ ク タ 、 メ ソ ッ ド 、 お よ び フ ィ ー ル ド に つ い て 説 明 し た 一 連 の HTML ペ ー ジ を 生 成 し ま す 。

javadoc ツ ー ル は 、 パ ッ ケ ー ジ 全 体 、 個 々 の ソ ー ス フ ァ イ ル 、 ま た は そ の 両 方 に 対 し て 実 行 で き ま す 。 javadoc ツ ー ル を パ ッ ケ ー ジ 全 体 に 対 し て 実 行 す る 場 合 は 、 一 連 の パ ッ ケ ー ジ 名 を javadoc に 引 数 と し て 渡 し ま す 。 個 々 の ク ラ ス に 対 し て javadoc を 実 行 す る 場 合 は 、 一 連 の ソ ー ス (.java) フ ァ イ ル 名 を 渡 し ま す 。 具 体 的 な 例 は 、 こ の ペ ー ジ の 最 後 で 示 し ま す 。

注 ) javadoc ツ ー ル に パ ッ ケ ー ジ 名 を 渡 す と 、 現 在 の リ リ ー ス で は 指 定 さ れ た パ ッ ケ ー ジ デ ィ レ ク ト リ 内 の す べ て の .java ク ラ ス が 処 理 さ れ ま す 。 こ れ は 、 .java フ ァ イ ル が コ ー ド 例 で あ る 場 合 や 指 定 さ れ た パ ッ ケ ー ジ の 実 際 の メ ン バ で は な い そ の 他 の ク ラ ス で あ る 場 合 も 同 様 で す 。 javadoc ツ ー ル は 、 パ ッ ケ ー ジ 宣 言 用 の 各 .java フ ァ イ ル を 解 析 し ま せ ん 。 将 来 の リ リ ー ス で は 、 こ の 解 析 を 追 加 す る 可 能 性 が あ り ま す 。

実 行 時 に 、 javadoc ツ ー ル は そ の 実 行 の 一 部 と し て 記 述 さ れ て い る パ ッ ケ ー ジ 、 ク ラ ス 、 お よ び メ ン バ の 名 称 に ク ロ ス リ フ ァ レ ン ス リ ン ク を 自 動 的 に 追 加 し ま す 。 リ ン ク は 、 次 の 箇 所 に 現 わ れ ま す 。

−link と −linkoffline オ プ シ ョ ン を 使 用 し て 、 コ マ ン ド 行 に 含 ま れ て い な い 、 個 別 に 生 成 さ れ る ク ラ ス の 既 存 の テ キ ス ト に ハ イ パ ー リ ン ク を 追 加 で き ま す 。

javadoc ツ ー ル は 、 実 行 の た び に ひ と つ の 完 全 な ド キ ュ メ ン ト を 生 成 し ま す 。 javadoc は 、 追 加 生 成 を 行 え ま せ ん 。 つ ま り 、 以 前 に 実 行 し た javadoc の 結 果 を 変 更 し た り 、 そ れ ら を 直 接 取 り 込 む こ と は で き ま せ ん 。 し か し 、 前 述 の よ う に ほ か の 実 行 の 結 果 に リ ン ク す る こ と は 可 能 で す 。

実 装 上 の 理 由 か ら 、 javadoc ツ ー ル は 実 行 に java コ ン パ イ ラ を 必 要 と し 、 java コ ン パ イ ラ に 依 存 し て い ま す 。 javadoc ツ ー ル は javac の 一 部 を 呼 び 出 し て 、 宣 言 を コ ン パ イ ル し 、 メ ン バ の 実 装 は 無 視 し ま す 。 javadoc ツ ー ル は 、 ク ラ ス 階 層 を 含 む ク ラ ス の 豊 富 な 内 部 表 現 、 お よ び 「 使 用 」 関 係 を 構 築 し 、 そ こ か ら HTML を 生 成 し ま す 。 javadoc ツ ー ル は 、 ソ ー ス コ ー ド の ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト か ら 、 ユ ー ザ の 提 供 す る ド キ ュ メ ン ト も 取 得 し ま す 。

javadoc ツ ー ル は 、 メ ソ ッ ド 本 体 の な い 純 粋 な ス タ ブ フ ァ イ ル で あ る .java ソ ー ス フ ァ イ ル 上 で 実 行 さ れ ま す 。 つ ま り 、 API の 作 成 時 に は 、 コ ー ド を 記 述 す る 前 の 設 計 の 早 い 段 階 で ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト を 記 述 し 、 javadoc を 実 行 で き ま す 。

コ ン パ イ ラ に 依 存 す る こ と に よ っ て 、 HTML 出 力 が 、 実 際 の 実 装 に 正 確 に 対 応 す る こ と が 保 証 さ れ ま す 。 実 際 の 実 装 は 、 明 示 的 で な く 暗 黙 的 に ソ ー ス コ ー ド に 依 存 し て い る 場 合 が あ り ま す 。 た と え ば 、 javadoc ツ ー ル は 、 .class フ ァ イ ル 内 に は 存 在 す る が 、 ソ ー ス コ ー ド 内 に は 存 在 し な い デ フ ォ ル ト コ ン ス ト ラ ク タ (「 Java Language Specification」 の セ ク シ ョ ン 8.6.7) を ド キ ュ メ ン ト 化 し ま す 。

多 く の 場 合 、 javadoc ツ ー ル で は 、 ソ ー ス フ ァ イ ル の コ ー ド が 不 完 全 ま た は エ ラ ー を 含 ん で い る 場 合 で も ド キ ュ メ ン ト を 生 成 で き ま す 。 こ の た め 、 デ バ ッ グ や ト ラ ブ ル シ ュ ー テ ィ ン グ が 完 了 す る 前 に ド キ ュ メ ン ト を 生 成 で き ま す 。 た と え ば 、 Java 言 語 仕 様 に よ る と 、 抽 象 メ ソ ッ ド を 含 む ク ラ ス は そ れ 自 体 を 抽 象 と 宣 言 し な け れ ば な り ま せ ん 。 こ の エ ラ ー を 検 出 す る と 、 javac コ ン パ イ ラ の 場 合 は 、 こ の エ ラ ー で 停 止 し ま す が 、 javadoc ツ ー ル は 警 告 を 出 さ ず に 処 理 を 進 め ま す 。 javadoc ツ ー ル は ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト の 基 本 的 な チ ェ ッ ク を 行 い ま す 。 ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト を よ り 詳 し く チ ェ ッ ク す る 必 要 が あ る 場 合 は 、 DocCheck ド ッ ク レ ッ ト を 使 用 し て く だ さ い 。

javadoc ツ ー ル が ド キ ュ メ ン ト 用 の 内 部 構 造 を 構 築 す る と き は 、 参 照 す る ク ラ ス を す べ て ロ ー ド し ま す 。 こ の た め 、 ブ ー ト ス ト ラ ッ プ ク ラ ス 、 拡 張 機 能 、 ま た は ユ ー ザ ク ラ ス に か か わ ら ず 、 javadoc ツ ー ル は 、 参 照 す る ク ラ ス を す べ て 検 出 で き な け れ ば な り ま せ ん 。 一 般 的 に 、 作 成 す る ク ラ ス は 、 拡 張 機 能 と し て ロ ー ド さ れ る か 、 javadoc ツ ー ル の ク ラ ス パ ス 内 に あ る 必 要 が あ り ま す 。

Javadoc ド ッ ク レ ッ ト
javadoc ツ ー ル の 出 力 の 内 容 と 形 式 は 、 ド ッ ク レ ッ ト を 使 っ て カ ス タ マ イ ズ で き ま す 。 javadoc ツ ー ル に は 、 標 準 ド ッ ク レ ッ ト と 呼 ば れ る デ フ ォ ル ト の 「 組 み 込 み 型 」 ド ッ ク レ ッ ト が あ り 、 こ れ に よ っ て HTML 形 式 の API ド キ ュ メ ン ト を 生 成 し ま す 。 標 準 ド ッ ク レ ッ ト の 修 正 や サ ブ ク ラ ス 化 を 行 な っ た り 、 HTML、 XML、 MIF、 RTF な ど の 好 み の 出 力 形 式 を 生 成 す る 独 自 の ド ッ ク レ ッ ト を 記 述 す る こ と も 可 能 で す 。 ド ッ ク レ ッ ト と そ の 使 用 法 に つ い て は 、 次 を 参 照 し て く だ さ い 。

-doclet コ マ ン ド 行 オ プ シ ョ ン で カ ス タ ム ド ッ ク レ ッ ト が 指 定 さ れ て い な い 場 合 、 javadoc ツ ー ル は 、 デ フ ォ ル ト の 標 準 ド ッ ク レ ッ ト を 使 用 し ま す 。 javadoc ツ ー ル に は 、 ど の ド ッ ク レ ッ ト が 使 わ れ て い る か に は 関 係 な く 使 用 で き る コ マ ン ド 行 オ プ シ ョ ン が あ り ま す 。 標 準 ド ッ ク レ ッ ト で は 、 こ れ ら の ほ か に 、 い く つ か の コ マ ン ド 行 オ プ シ ョ ン が 追 加 さ れ ま す 。 ど ち ら の オ プ シ ョ ン に つ い て も 、 後 述 の 「 オ プ シ ョ ン 」 で 説 明 し ま す 。

関 連 ド キ ュ メ ン ト お よ び ド ッ ク レ ッ ト

用 語
い く つ か の 用 語 に は 、 javadoc ツ ー ル の コ ン テ キ ス ト で 特 定 の 意 味 が あ り ま す 。
生 成 さ れ る ド キ ュ メ ン ト

javadoc ツ ー ル が Java ソ ー ス コ ー ド 内 の doc コ メ ン ト か ら 生 成 し た ド キ ュ メ ン ト の こ と で す 。 デ フ ォ ル ト の 生 成 ド キ ュ メ ン ト は HTML 形 式 で 、 標 準 ド ッ ク レ ッ ト に よ っ て 作 成 さ れ ま す 。

ド キ ュ メ ン ト 化 さ れ る ク ラ ス

javadoc の 実 行 に よ っ て 完 全 な ド キ ュ メ ン ト が 生 成 さ れ る ク ラ ス と イ ン タ フ ェ ー ス で す 。 ド キ ュ メ ン ト 化 す る に は 、 ソ ー ス フ ァ イ ル が 使 用 可 能 で な け れ ば な ら ず 、 ソ ー ス フ ァ イ ル 名 ま た は パ ッ ケ ー ジ 名 の ど ち ら か を javadoc コ マ ン ド に 渡 さ な け れ ば な り ま せ ん 。 ド キ ュ メ ン ト 化 さ れ る ク ラ ス は 、 javadoc の 実 行 で 組 み 込 ま れ る ク ラ ス 、 つ ま り 「 組 み 込 み ク ラ ス 」 と も 呼 ば れ ま す 。

除 外 さ れ る ク ラ ス

javadoc コ マ ン ド に ソ ー ス フ ァ イ ル 名 ま た は パ ッ ケ ー ジ 名 が 渡 さ れ な い ク ラ ス と イ ン タ フ ェ ー ス で す 。

ソ ー ス フ ァ イ ル
javadoc ツ ー ル は 、 Java 言 語 ソ ー ス フ ァ イ ル (.java)、 パ ッ ケ ー ジ コ メ ン ト フ ァ イ ル 、 概 要 コ メ ン ト フ ァ イ ル 、 お よ び そ の 他 の 処 理 さ れ な い フ ァ イ ル の 4 種 類 の 「 ソ ー ス 」 フ ァ イ ル を 基 に し て 、 出 力 を 生 成 し ま す 。

ク ラ ス ソ ー ス コ ー ド フ ァ イ ル
各 ク ラ ス ま た は イ ン タ フ ェ ー ス 、 お よ び そ の メ ン バ は 、 .java フ ァ イ ル の 中 に そ れ 自 身 の ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト を 持 つ こ と が で き ま す 。 ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト の 詳 細 に つ い て は 、 「 ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト 」 の 節 を 参 照 し て く だ さ い 。

パ ッ ケ ー ジ コ メ ン ト フ ァ イ ル
各 パ ッ ケ ー ジ は 、 独 自 の ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト を 持 つ こ と が で き 、 「 ソ ー ス 」 フ ァ イ ル に 保 持 し ま す 。 javadoc ツ ー ル は 、 生 成 す る パ ッ ケ ー ジ の 要 約 ペ ー ジ に こ の コ メ ン ト を マ ー ジ し ま す 。 通 常 、 こ の コ メ ン ト に は 、 パ ッ ケ ー ジ 全 体 に 適 用 さ れ る ド キ ュ メ ン ト を 含 め ま す 。

パ ッ ケ ー ジ コ メ ン ト フ ァ イ ル を 作 成 す る に は 、 フ ァ イ ル 名 を package.html に し て .java フ ァ イ ル と と も に ソ ー ス ツ リ ー 内 の パ ッ ケ ー ジ デ ィ レ ク ト リ に 置 く 必 要 が あ り ま す 。 javadoc ツ ー ル は 、 こ の 場 所 で こ の フ ァ イ ル 名 を 自 動 的 に 検 索 し ま す 。 フ ァ イ ル 名 は 、 ど の パ ッ ケ ー ジ で も 同 一 で す 。

パ ッ ケ ー ジ コ メ ン ト フ ァ イ ル の 内 容 は 、 ほ か の す べ て の コ メ ン ト と 同 様 に 、 HTML で 記 述 さ れ た 1 つ の 大 き な ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト で す が 、 ほ か の コ メ ン ト と 異 な る 点 が 1 つ だ け あ り ま す 。 そ れ は 、 こ の ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト に は /** と */、 お よ び 行 頭 の ア ス タ リ ス ク の コ メ ン ト 区 切 り 文 字 を 含 め て は な ら な い こ と で す 。 コ メ ン ト を 書 く 場 合 は 、 最 初 の 文 を パ ッ ケ ー ジ の 要 約 に し 、 <body> と 最 初 の 文 の 間 に タ イ ト ル ま た は そ の 他 の テ キ ス ト を 含 め て は な り ま せ ん 。 パ ッ ケ ー ジ タ グ を 含 め る こ と は で き ま す が 、 他 の ド キ ュ メ ン ト コ メ ン ト と 同 様 、 {@link} 以 外 の タ グ は 、 説 明 の あ と に 置 か な け れ ば な り ま せ ん 。 @see タ グ を パ ッ ケ ー ジ コ メ ン ト フ ァ イ ル に 追 加 す る 場 合 は 、 完 全 指 定 さ れ た 名 前 を 使 用 す る 必 要 が あ り ま す 。

javadoc ツ ー ル は 、 実 行 時 に こ の フ ァ イ ル を 自 動 的 に 検 索 し ま す 。 こ の フ ァ イ ル を 見 つ け る と 、 javadoc ツ ー ル は 次 の 処 理 を 行 い ま す 。

概 要 コ メ ン ト フ ァ イ ル
ド キ ュ メ ン ト 化 す る 各 ア プ リ ケ ー シ ョ ン ま た は パ ッ ケ ー ジ の セ ッ ト は 、 独 自 の 概 要 ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト を 持 つ こ と が で き 、 そ れ は 「 ソ ー ス 」 フ ァ イ ル に 保 持 さ れ ま す 。 javadoc ツ ー ル は 、 生 成 す る 概 要 ペ ー ジ に こ の コ メ ン ト を マ ー ジ し ま す 。 通 常 、 こ の コ メ ン ト に は 、 ア プ リ ケ ー シ ョ ン ま た は パ ッ ケ ー ジ の セ ッ ト 全 体 に 当 て は ま る ド キ ュ メ ン ト を 含 め ま す 。

概 要 コ メ ン ト フ ァ イ ル を 作 成 す る 場 合 、 フ ァ イ ル に 好 き な 名 前 を 付 け て 、 好 き な 場 所 に 置 く こ と が で き ま す が 、 通 常 は フ ァ イ ル 名 を overview.html に し て 、 ソ ー ス ツ リ ー の 一 番 上 の 階 層 に 置 き ま す 。 異 な る パ ッ ケ ー ジ の セ ッ ト に 対 し て javadoc を 複 数 回 実 行 し た い 場 合 に は 、 1 つ の ソ ー ス フ ァ イ ル の セ ッ ト に 対 し て 複 数 の 概 要 コ メ ン ト フ ァ イ ル を 作 成 で き ま す 。 た と え ば 、 java.applet パ ッ ケ ー ジ の ソ ー ス フ ァ イ ル が /home/user/src/java/applet デ ィ レ ク ト リ に 含 ま れ て い る と す る と 、 /home/user/src/overview.html に 概 要 コ メ ン ト フ ァ イ ル を 作 成 す る こ と が で き ま す 。

概 要 コ メ ン ト フ ァ イ ル の 内 容 は 、 前 に 述 べ た パ ッ ケ ー ジ コ メ ン ト フ ァ イ ル と 同 様 、 HTML で 記 述 さ れ た 1 つ の 大 き な ド キ ュ メ ン ト コ メ ン ト で す 。 詳 細 は 、 前 述 の 説 明 を 参 照 し て く だ さ い 。 繰 り 返 し に な り ま す が 、 こ の コ メ ン ト を 書 く 場 合 は 、 最 初 の 文 を ア プ リ ケ ー シ ョ ン ま た は パ ッ ケ ー ジ の セ ッ ト の 要 約 に し 、 <body> と 最 初 の 文 の 間 に タ イ ト ル ま た は そ の 他 の テ キ ス ト を 含 め て は な り ま せ ん 。 概 要 タ グ を 含 め る こ と が で き ま す 。 ど の ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト に つ い て も 、 {@link} 以 外 の タ グ は 、 説 明 の あ と に 置 く 必 要 が あ り ま す 。 @see タ グ を 追 加 す る 場 合 は 、 完 全 指 定 の 名 前 を 使 用 す る 必 要 が あ り ま す 。

javadoc ツ ー ル の 実 行 時 に 、 −overview オ プ シ ョ ン を 使 っ て 概 要 コ メ ン ト フ ァ イ ル 名 を 指 定 し ま す 。 フ ァ イ ル は 、 パ ッ ケ ー ジ コ メ ン ト フ ァ イ ル と 同 じ よ う に 処 理 さ れ ま す 。

そ の 他 の 処 理 さ れ な い フ ァ イ ル
ソ ー ス に は 、 javadoc ツ ー ル で 生 成 先 の デ ィ レ ク ト リ に コ ピ ー す る 、 そ の 他 の 任 意 の フ ァ イ ル を 含 め る こ と が で き ま す 。 一 般 に 、 こ の よ う な フ ァ イ ル に は 、 サ ン プ ル の グ ラ フ ィ ッ ク フ ァ イ ル 、 Java ソ ー ス (.java) お よ び ク ラ ス (.class) フ ァ イ ル 、 内 容 が 通 常 の Java ソ ー ス フ ァ イ ル の ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト の 影 響 を 受 け な い 独 立 し た HTML フ ァ イ ル な ど が あ り ま す 。

処 理 さ れ な い フ ァ イ ル を 含 め る に は 、 そ れ ら の フ ァ イ ル を doc-files と い う デ ィ レ ク ト リ に 置 き ま す 。 こ の デ ィ レ ク ト リ は 、 任 意 の パ ッ ケ ー ジ デ ィ レ ク ト リ の 下 に 作 成 で き ま す 。 パ ッ ケ ー ジ ご と に こ の よ う な サ ブ デ ィ レ ク ト リ を 1 つ 持 つ こ と が で き ま す 。 こ の サ ブ デ ィ レ ク ト リ に は 、 イ メ ー ジ 、 サ ン プ ル コ ー ド 、 ソ ー ス フ ァ イ ル 、 .class フ ァ イ ル 、 ア プ レ ッ ト 、 お よ び HTML フ ァ イ ル を 入 れ る こ と が で き ま す 。 た と え ば 、 ボ タ ン の 画 像 button.gif を java.awt.Button ク ラ ス ド キ ュ メ ン ト に 含 め た い 場 合 は 、 そ の フ ァ イ ル を /home/user/src/java/awt/doc-files/ デ ィ レ ク ト リ に 置 き ま す 。 doc-files デ ィ レ ク ト リ を /home/user/src/java/doc-files に 置 く こ と は で き ま せ ん 。 こ れ は 、 java は パ ッ ケ ー ジ で は な く 、 そ の デ ィ レ ク ト リ そ の も の に ソ ー ス フ ァ イ ル が 入 っ て い な い か ら で す 。

こ れ ら の 処 理 さ れ な い フ ァ イ ル へ の リ ン ク は す べ て 明 示 的 に 記 述 す る 必 要 が あ り ま す 。 こ れ は 、 javadoc ツ ー ル が フ ァ イ ル を 見 ず に 、 単 に デ ィ レ ク ト リ と そ の 内 容 物 を 生 成 先 に コ ピ ー す る だ け だ か ら で す 。 た と え ば 、 Button.java ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト 内 の リ ン ク は 、 次 の よ う に な り ま す 。

/**
* This button looks like this:
* <img src="doc-files/Button.gif">
*/

生 成 さ れ る フ ァ イ ル
デ フ ォ ル ト で は 、 javadoc は 、 HTML 形 式 の ド キ ュ メ ン ト を 生 成 す る 標 準 ド ッ ク レ ッ ト を 使 い ま す 。 こ の ド ッ ク レ ッ ト は 、 以 下 の 種 類 の フ ァ イ ル を 生 成 し ま す 。 以 下 の 各 HTML「 ペ ー ジ 」 は 、 そ れ ぞ れ 別 の フ ァ イ ル に 対 応 し ま す 。 javadoc が 生 成 す る フ ァ イ ル の 名 前 に は 、 ク ラ ス や イ ン タ フ ェ ー ス の 名 前 に ち な ん だ も の と 、 そ う で な い も の (package-summary.html な ど ) の 2 種 類 が あ り ま す 。 後 者 の グ ル ー プ に は 、 前 者 の グ ル ー プ の 名 前 と フ ァ イ ル 名 が 競 合 し な い よ う に 、 ハ イ フ ン が 含 ま れ て い ま す 。

基 本 内 容 ペ ー ジ

相 互 参 照 ペ ー ジ

サ ポ ー ト フ ァ イ ル

HTML フ レ ー ム
javadoc ツ ー ル は 、 下 の 図 に 示 す よ う に 、 2 つ か 3 つ の HTML フ レ ー ム を 生 成 し ま す 。 ソ ー ス フ ァ イ ル (*.java) ま た は 単 一 の パ ッ ケ ー ジ 名 を 引 数 と し て javadoc コ マ ン ド に 渡 す 場 合 は 、 左 側 の 列 に ク ラ ス の 一 覧 を 表 示 す る フ レ ー ム (C) 1 つ だ け が 作 成 さ れ ま す 。 javadoc に 複 数 の パ ッ ケ ー ジ 名 を 渡 す 場 合 は 、 概 要 ペ ー ジ (Detail) に 加 え て 、 す べ て の パ ッ ケ ー ジ の 一 覧 を 表 示 す る 第 3 の フ レ ー ム (P) が 作 成 さ れ ま す 。 こ の 概 要 ペ ー ジ の フ ァ イ ル 名 は overview-summary.html で す 。 し た が っ て 、 こ の フ ァ イ ル が 作 成 さ れ る の は 、 2 つ 以 上 の パ ッ ケ ー ジ 名 を 渡 し た 場 合 だ け で す 。 [フ レ ー ム な し ] リ ン ク を ク リ ッ ク す る か 、 overview-summary.html か ら 表 示 す る よ う に す る と 、 フ レ ー ム を 省 略 で き ま す 。

HTML フ レ ー ム に 慣 れ て い な い 場 合 は 、 フ レ ー ム に は 、 印 刷 お よ び ス ク ロ ー ル 用 の 「 フ ォ ー カ ス 」 が 必 要 で あ る こ と に 注 意 す る 必 要 が あ り ま す 。 フ レ ー ム に フ ォ ー カ ス を 与 え る に は 、 そ の フ レ ー ム を ク リ ッ ク し ま す 。 す る と 、 多 く の ブ ラ ウ ザ で は 、 矢 印 キ ー お よ び ペ ー ジ キ ー を 使 っ て そ の フ レ ー ム を ス ク ロ ー ル し た り 、 [印 刷 ] メ ニ ュ ー コ マ ン ド を 使 っ て そ の フ レ ー ム を 印 刷 し た り で き る よ う に な り ま す 。

------------ ------------
|C| Detail | |P| Detail |
| | | | | |
| | | |-| |
| | | |C| |
| | | | | |
| | | | | |
------------ ------------
javadoc *.java javadoc java.lang java.awt

HTML フ レ ー ム が 必 要 か ど う か に よ っ て 、 次 の ど ち ら か の フ ァ イ ル を 開 始 ペ ー ジ と し て ロ ー ド し ま す 。

生 成 さ れ る フ ァ イ ル 構 造
生 成 さ れ る ク ラ ス フ ァ イ ル お よ び イ ン タ フ ェ ー ス フ ァ イ ル は 、 Java ソ ー ス フ ァ イ ル お よ び ク ラ ス フ ァ イ ル と 同 じ デ ィ レ ク ト リ 階 層 で 組 織 さ れ ま す 。 こ の 構 造 は 、 1 つ の サ ブ パ ッ ケ ー ジ に つ き 1 つ の デ ィ レ ク ト リ で 構 成 さ れ ま す 。

た と え ば 、 java.applet.Applet ク ラ ス に 対 し て 生 成 さ れ る ド キ ュ メ ン ト は 、 java/applet/Applet.html に 格 納 さ れ ま す 。 生 成 先 の デ ィ レ ク ト リ の 名 前 が apidocs だ と す る と 、 java.applet パ ッ ケ ー ジ の フ ァ イ ル 構 造 も こ れ に 従 い ま す 。 前 述 し た よ う に 、 「 frame」 と い う 語 を 名 前 に 含 む フ ァ イ ル は 、 す べ て 左 上 ま た は 左 下 の フ レ ー ム に 表 示 さ れ ま す 。 そ れ 以 外 の HTML フ ァ イ ル は 、 す べ て 右 側 の フ レ ー ム に 表 示 さ れ ま す 。

注 : デ ィ レ ク ト リ は 、 太 字 (bold) で 示 し て あ り ま す 。 ア ス タ リ ス ク (*) は 、 javadoc へ の 引 数 が パ ッ ケ ー ジ 名 で な く ソ ー ス フ ァ イ ル 名 (*.java) の と き に 、 省 略 さ れ る フ ァ イ ル お よ び デ ィ レ ク ト リ を 示 し て い ま す 。 ま た 、 引 数 が ソ ー ス フ ァ イ ル 名 の と き に は 、 package-list は 作 成 さ れ ま す が 、 空 で す 。 doc-files デ ィ レ ク ト リ は 、 ソ ー ス ツ リ ー 内 に 存 在 し な い 限 り 、 生 成 先 に 表 示 さ れ ま せ ん 。

生 成 さ れ る API 宣 言
javadoc ツ ー ル は 、 各 ク ラ ス 、 イ ン タ フ ェ ー ス 、 フ ィ ー ル ド 、 コ ン ス ト ラ ク タ 、 お よ び メ ソ ッ ド の 説 明 の 初 め で 宣 言 を 生 成 し ま す 。 こ の 宣 言 は 、 そ の API 項 目 の 宣 言 で す 。 た と え ば 、 ブ ー ル 型 ク ラ ス の 宣 言 は 次 の よ う に な り ま す 。

public final class Boolean
extends Object
implements Serializable

Boolean.valueOf メ ソ ッ ド の 宣 言 は 次 の よ う に な り ま す 。

public static Boolean valueOf(String s)

javadoc ツ ー ル は 修 飾 子 public 、 protected 、 private 、 abstract 、 final 、 static 、 transient 、 お よ び volatile を 組 み 込 む こ と が で き ま す が 、 synchronized と native は 組 み 込 む こ と が で き ま せ ん 。 synchronized と native修 飾 子 は 実 装 の 詳 細 と 見 な さ れ 、 API 仕 様 の 一 部 と は 見 な さ れ ま せ ん 。

キ ー ワ ー ド synchronized に 依 存 す る よ り も 、 「 複 数 の ス レ ッ ド に よ っ て 単 一 の Enumeration を 並 行 し て 使 用 し て は な ら な い 」 と い う よ う に 、 並 行 処 理 の セ マ ン テ ィ ッ ク ス を コ メ ン ト 説 明 の 中 で ド キ ュ メ ン ト 化 す る べ き で す 。 ド キ ュ メ ン ト で は 、 こ れ ら の セ マ ン テ ィ ッ ク ス の 達 成 方 法 を 説 明 す べ き で は あ り ま せ ん 。 別 の 例 を 挙 げ る と 、 Hashtable は ス レ ッ ド に 対 し て 安 全 で な け れ ば な り ま せ ん が 、 エ ク ス ポ ー ト さ れ る そ の メ ソ ッ ド す べ て を 同 期 さ せ る こ と に よ っ て こ れ を 実 現 す る と 明 記 す る 必 要 は な い と い う こ と で す 。 バ ケ ッ ト レ ベ ル で 内 部 的 に 同 期 を と る 権 限 を 留 保 し て 、 よ り 高 度 な 並 行 性 を 提 供 す べ き で す 。

ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト : ソ ー ス コ ー ド へ の コ メ ン ト の 挿 入
オ リ ジ ナ ル の 「 ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト の 仕 様 」 は 、 「 関 連 項 目 」 を 参 照 し て く だ さ い 。 ソ ー ス コ ー ド の 任 意 の 宣 言 (ク ラ ス 、 イ ン タ フ ェ ー ス 、 メ ソ ッ ド 、 コ ン ス ト ラ ク タ 、 ま た は フ ィ ー ル ド ) の 前 に 、 ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト (doc コ メ ン ト ) を 記 述 す る こ と が で き ま す 。 各 パ ッ ケ ー ジ に ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト を 作 成 で き 、 構 文 は 若 干 異 な り ま す が 、 概 要 に も ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト を 作 成 で き ま す 。 ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト は 、 Javadoc コ メ ン ト と も 呼 ば れ ま す 。 ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト は 、 コ メ ン ト の 始 ま り を 示 す 文 字 列 /**
と 、 コ メ ン ト の 終 わ り を 示 す 文 字 列 */ の 間 に あ る 文 字 で 構 成 さ れ ま す 。 行 頭 の ア ス タ リ ス ク は 、 各 行 に 記 述 で き ま す 。 詳 細 は 、 以 下 で 説 明 し ま す 。 Linux で は テ キ ス ト は 、 複 数 行 に わ た っ て 記 述 で き ま す 。

/**
* This is the typical format of a simple documentation comment.
* that spans two lines.
*/

次 の よ う に 、 コ メ ン ト は 1 行 に ま と め る こ と も で き ま す 。

/** This comment takes up only one line. */

コ メ ン ト の 配 置 - ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト が 認 識 さ れ る の は 、 ク ラ ス 、 イ ン タ フ ェ ー ス 、 コ ン ス ト ラ ク タ 、 メ ソ ッ ド 、 ま た は フ ィ ー ル ド 宣 言 の 前 に 置 か れ た 場 合 だ け で す (ク ラ ス 、 メ ソ ッ ド 、 お よ び フ ィ ー ル ド の 例 を 参 照 )。 メ ソ ッ ド の 本 体 に 置 か れ た ド キ ュ メ ン ト コ メ ン ト は 無 視 さ れ ま す 。 javadoc ツ ー ル は 、 宣 言 文 ご と に 1 つ の ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト だ け を 認 識 し ま す 。

よ く 発 生 す る 間 違 い は 、 重 要 な 文 を ク ラ ス コ メ ン ト と ク ラ ス 宣 言 の 間 に 入 れ て し ま う こ と で す 。 javadoc は ク ラ ス コ メ ン ト を 無 視 す る た め 、 注 意 し て く だ さ い 。

/**
* This is the class comment for the class Whatever.
*/

import com.sun; // MISTAKE - Important not to put statements here

public class Whatever {
}

コ メ ン ト の 説 明 の あ と に タ グ が 続 く - コ メ ン ト の 開 始 区 切 り 文 字 で あ る /** の あ と か ら タ グ セ ク シ ョ ン ま で が 説 明 に な り ま す 。 タ グ セ ク シ ョ ン は 、 先 頭 文 字 が @ で あ る 行 か ら 始 ま り ま す (行 の 先 頭 の ア ス タ リ ス ク お よ び 空 白 文 字 は 除 く )。 説 明 を 記 述 せ ず 、 コ メ ン ト だ け の タ グ を 記 述 す る こ と も で き ま す 。 説 明 は 、 タ グ セ ク シ ョ ン 以 降 に 続 け る こ と は で き ま せ ん 。 タ グ の 引 数 は 複 数 の 行 に ま た が っ て 記 述 で き ま す 。 タ グ の 数 に 制 限 は あ り ま せ ん 。 何 回 も 記 述 で き る タ グ と 、 1 回 し か 記 述 で き な い タ グ が あ り ま す 。 次 の 例 の @see か ら タ グ セ ク シ ョ ン が 始 ま り ま す 。

/**
* This is a doc comment.
* @see java.lang.Object
*/

標 準 タ グ と イ ン ラ イ ン タ グ : タ グ は 、 javadoc ツ ー ル が 処 理 で き る 、 doc コ メ ン ト 内 の 特 別 な キ ー ワ ー ド で す 。 javadoc ツ ー ル に は 、 @tag と し て 現 れ る 標 準 タ グ と 、 中 括 弧 内 に {@tag} と し て 現 れ る イ ン ラ イ ン タ グ が あ り ま す 。 解 釈 さ せ る た め に は 、 先 頭 の ア ス タ リ ス ク 、 空 白 、 コ メ ン ト 区 切 り 文 字 (/**) を 除 い て は 標 準 タ グ が 行 の 先 頭 で あ る よ う に 配 置 す る 必 要 が あ り ま す 。 つ ま り 、 ユ ー ザ は テ キ ス ト 内 の 任 意 の 位 置 で @ 文 字 を 使 用 で き 、 こ の 文 字 は タ グ の 始 め と は 解 釈 さ れ ま せ ん 。 @ 文 字 で 行 を 開 始 し て こ れ が 解 釈 さ れ な い よ う に し た い 場 合 は 、 HTML エ ン テ ィ テ ィ の &#064; を 使 用 し て く だ さ い 。 各 ス タ ン ド ア ロ ン タ グ に は 関 連 す る テ キ ス ト が あ り ま す 。 こ れ は 、 そ の タ グ の 後 か ら 次 の タ グ の 直 前 ま で 、 ま た は doc コ メ ン ト の 最 後 ま で の 任 意 の テ キ ス ト で す 。 関 連 付 け ら れ た テ キ ス ト は 、 複 数 行 に ま た が っ て 記 述 で き ま す 。 イ ン ラ イ ン タ グ は 、 そ の テ キ ス ト が 許 可 さ れ る 位 置 に は ど こ で も 指 定 で き 、 解 釈 の 対 象 と な り ま す 。 次 の 例 は 、 標 準 タ グ @deprecated と イ ン ラ イ ン タ グ {@link} が 含 ま れ て い ま す 。

/**
* @deprecated As of JDk 1.1, replaced by {@link #setBounds(int,int,int,int)}
*/

コ メ ン ト は HTML で 記 述 し ま す 。 テ キ ス ト は HTML で 記 述 し な け れ ば な り ま せ ん 。 こ れ は 、 HTML の エ ン テ ィ テ ィ を 使 う 必 要 が あ る こ と 、 お よ び HTML タ グ を 使 用 で き る こ と を 意 味 し ま す 。 HTML は 、 使 用 す る ブ ラ ウ ザ が サ ポ ー ト す る 任 意 の バ ー ジ ョ ン を 使 う こ と が で き ま す 。 標 準 ド ッ ク レ ッ ト は 、 階 層 式 ス タ イ ル シ ー ト と フ レ ー ム を 含 む ほ か の 部 分 (ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト 以 外 ) は 、 HTML 3.2 に 準 拠 し た コ ー ド を 生 成 す る よ う に 記 述 さ れ て い ま す (フ レ ー ム セ ッ ト 対 応 の た め 、 生 成 さ れ る 各 フ ァ イ ル は 、 「 HTML 4.0」 で 始 ま る )。

た と え ば 、 よ り 小 さ い (<) お よ び よ り 大 き い (>) と い う 記 号 は 、 &lt; と &gt; と 記 述 す る 必 要 が あ り ま す 。 同 様 に 、 ア ン パ サ ン ド (&) は 、 &amp; と 記 述 す る 必 要 が あ り ま す 。 次 の 例 で は 、 ボ ー ル ド の HTML タ グ <b> を 示 し ま す 。

次 に doc コ メ ン ト を 示 し ま す 。

/**
* This is a <b>doc</b> comment.
* @see java.lang.Object
*/

行 頭 の ア ス タ リ ス ク - javadoc は 、 doc コ メ ン ト を 解 析 す る と き に 、 各 行 の 先 頭 に あ る 文 字 ア ス タ リ ス ク (*) を す べ て 破 棄 し ま す 。 ま た 、 最 初 の ア ス タ リ ス ク (*) よ り 前 の 空 白 と タ ブ も 破 棄 し ま す 。 し た が っ て 、 行 頭 の 空 白 を そ の ま ま に し て お き た い 場 合 は 、 先 頭 の ア ス タ リ ス ク を 省 略 し て は な り ま せ ん 。 た と え ば 、 <pre> タ グ を 使 っ て 、 サ ン プ ル コ ー ド を イ ン デ ン ト す る 場 合 な ど で す 。

最 初 の 文 - 各 doc コ メ ン ト の 最 初 の 文 は 、 宣 言 さ れ て い る エ ン テ ィ テ ィ に 関 す る 簡 潔 か つ 完 全 な 説 明 を 含 む 要 約 文 で な け れ ば な り ま せ ん 。 こ の 文 は 、 空 白 、 タ ブ 、 ま た は 行 末 記 号 が 続 い て い る 最 初 の ピ リ オ ド 、 あ る い は 最 初 の ス タ ン ド ア ロ ン タ グ で 終 了 し ま す 。 javadoc ツ ー ル は 、 HTML ペ ー ジ の 最 初 に あ る メ ン バ 要 約 に 、 こ の 最 初 の 文 を コ ピ ー し ま す 。 文 の 区 切 り を 判 別 す る 方 法 が 将 来 の リ リ ー ス で ど の よ う に 変 更 さ れ る か に つ い て は 、 -breakiterator を 参 照 し て く だ さ い 。

複 数 フ ィ ー ル ド の 宣 言 - java で は 、 単 一 の 文 で 複 数 の フ ィ ー ル ド を 宣 言 で き ま す 。 し か し 、 こ の 文 の ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト は 1 つ だ け で 、 こ の コ メ ン ト が す べ て の フ ィ ー ル ド に コ ピ ー さ れ ま す 。 し た が っ て 、 フ ィ ー ル ド ご と に 個 々 の ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト を 付 け た い 場 合 は 、 各 フ ィ ー ル ド を 異 な る 文 で 宣 言 し な け れ ば な り ま せ ん 。 た と え ば 、 次 の ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト は 単 一 の 宣 言 と し て は 意 味 を 成 さ ず 、 2 つ の 宣 言 と し て 処 理 す る べ き で す 。

/**
* The horizontal and vertical distances of point (x,y)
*/
public int x, y; // Avoid this

javadoc ツ ー ル は 、 上 記 コ ー ド か ら 次 の ド キ ュ メ ン ト を 生 成 し ま す 。

public int x
The horizontal and vertical distances of point (x,y).
public int y
The horizontal and vertical distances of point (x,y).

ヘ ッ ダ タ グ を 使 用 す る と き は 注 意 し て く だ さ い 。 メ ン バ 用 の ド キ ュ メ ン ト コ メ ン ト を 書 く と き は 、 <H1> や <H2> な ど の HTML ヘ ッ ダ タ グ を 使 用 し な い で く だ さ い 。 こ れ は 、 javadoc が 全 ド キ ュ メ ン ト を 構 造 化 し て 生 成 す る た め 、 こ れ ら の 構 造 化 タ グ を 使 用 す る と 、 ド キ ュ メ ン ト の 書 式 が 乱 れ る 可 能 性 が あ る た め で す 。 し か し 、 ク ラ ス や パ ッ ケ ー ジ の コ メ ン ト で は 、 こ れ ら の ヘ ッ ダ タ グ を 使 用 し て 構 造 化 を 指 示 し て く だ さ い 。

メ ソ ッ ド コ マ ン ド の 自 動 再 利 用
javadoc ツ ー ル に は 、 ク ラ ス お よ び イ ン タ フ ェ ー ス 内 の メ ソ ッ ド の コ メ ン ト を 自 動 的 に 再 利 用 す る 、 つ ま り 「 継 承 」 す る 機 能 が あ り ま す 。 メ ソ ッ ド コ メ ン ト に 記 述 や @return、 @param、 @see、 @throws と い っ た タ グ が な い 場 合 、 javadoc ツ ー ル は 、 そ の メ ソ ッ ド が オ ー バ ー ラ イ ド ま た は 実 装 し て い る メ ソ ッ ド の コ メ ン ト と タ グ (存 在 す る 場 合 ) を 代 わ り に コ ピ ー し ま す 。 そ の 際 の ア ル ゴ リ ズ ム は 、 以 下 の と お り で す 。

つ ま り 、 特 定 の パ ラ メ ー タ の @param タ グ が 見 つ か ら な い 場 合 、 そ の パ ラ メ ー タ の コ メ ン ト が コ ピ ー さ れ ま す 。 特 定 の 例 外 の @throws タ グ が 見 つ か ら な い 場 合 、 そ の 例 外 が 宣 言 さ れ て い る 場 合 に 限 り 、 そ の @throws タ グ が コ ピ ー さ れ ま す 。

こ の 動 作 は 、 バ ー ジ ョ ン 1.3 以 前 と は 対 照 的 で す 。 以 前 の バ ー ジ ョ ン で は 、 説 明 や タ グ が 存 在 す れ ば 、 コ メ ン ト は 一 切 継 承 さ れ ま せ ん で し た 。

ま た 、 説 明 ま た は 任 意 の タ グ に イ ン ラ イ ン タ グ {@inheritDoc} が 含 ま れ る 場 合 、 対 応 す る 説 明 ま た は タ グ が そ の 位 置 に コ ピ ー さ れ ま す 。

オ ー バ ー ラ イ ド さ れ て い る メ ソ ッ ド は 、 ド キ ュ メ ン ト 化 さ れ る ク ラ ス の メ ン バ で な け れ ば な ら ず 、 か つ 、 外 部 参 照 ク ラ ス の メ ン バ で あ っ て は な り ま せ ん 。 そ う で な い と 、 コ ピ ー す る ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト を 実 際 に は 取 得 で き ま せ ん 。

コ メ ン ト の 継 承 は 次 の 場 合 に 行 わ れ ま す 。

最 初 の 2 つ の ケ ー ス (メ ソ ッ ド が オ ー バ ー ラ イ ド し て い る 場 合 ) で は 、 javadoc ツ ー ル は 、 オ ー バ ー ラ イ ド し て い る メ ソ ッ ド の ド キ ュ メ ン ト 内 に 「 オ ー バ ー ラ イ ド 」 と い う 小 見 出 し を 生 成 し 、 オ ー バ ー ラ イ ド さ れ て い る メ ソ ッ ド へ の リ ン ク を 書 き 込 み ま す 。

3 つ 目 の ケ ー ス (特 定 の ク ラ ス の メ ソ ッ ド が イ ン タ フ ェ ー ス の メ ソ ッ ド を 実 装 し て い る 場 合 ) で は 、 javadoc ツ ー ル は 、 実 装 し て い る メ ソ ッ ド の ド キ ュ メ ン ト 内 に 「 定 義 」 と い う 小 見 出 し を 生 成 し 、 実 装 さ れ て い る メ ソ ッ ド へ の リ ン ク を 書 き 込 み ま す 。

メ ソ ッ ド の 説 明 が 継 承 さ れ る ア ル ゴ リ ズ ム - あ る メ ソ ッ ド に ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト が 記 述 さ れ て い な い 場 合 、 javadoc ツ ー ル は 、 次 の よ う な ア ル ゴ リ ズ ム を 使 用 し て 適 切 な コ メ ン ト を 検 索 し ま す 。 こ の ア ル ゴ リ ズ ム は 、 も っ と も 適 切 な ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト を 検 索 で き る よ う に 設 計 さ れ て お り 、 ス ー パ ー ク ラ ス よ り も イ ン タ フ ェ ー ス が 優 先 さ れ る よ う に な っ て い ま す 。

(そ の 際 の 順 序 は 、 手 順 1 で イ ン タ フ ェ ー ス を 調 べ た と き の 順 序 と 同 じ )

a. ス ー パ ー ク ラ ス に こ の メ ソ ッ ド に つ い て の ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト が
記 述 さ れ て い れ ば 、 そ の コ メ ン ト を 採 用 す る
b. 手 順 3a で ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト が 見 つ か ら な か っ た 場 合 は 、
ス ー パ ー ク ラ ス に 対 し て 、 こ の ア ル ゴ リ ズ ム 全 体 を 適 用 す る

javadoc の タ グ
javadoc ツ ー ル は 、 java doc コ メ ン ト 内 に 埋 め 込 ま れ た 特 殊 な タ グ を 解 析 し ま す 。 こ れ ら の 特 殊 な doc タ グ を 使 う と 、 書 式 の 整 っ た 完 全 な API ド キ ュ メ ン ト を ソ ー ス コ ー ド か ら 自 動 的 に 生 成 で き ま す 。 タ グ は 、 単 価 記 号 (@) で 始 ま り 、 大 文 字 小 文 字 が 区 別 さ れ ま す 。 こ れ ら の タ グ は 、 以 下 に 示 す と お り に 、 大 文 字 と 小 文 字 を 区 別 し て 入 力 す る 必 要 が あ り ま す 。 タ グ は 、 行 の 先 頭 (た だ し 先 行 す る 空 白 と 省 略 可 能 な ア ス タ リ ス ク は 除 く ) か ら 始 め な け れ ば な り ま せ ん 。 慣 習 上 、 同 じ 名 前 の タ グ は 1 個 所 に ま と め て 記 述 し ま す 。 た と え ば 、 @see タ グ が 複 数 あ る 場 合 は 、 す べ て を 1 個 所 に ま と め て 記 述 し ま す 。

タ グ は 次 の 2 種 類 あ り ま す 。

• ス タ ン ド ア ロ ン タ グ - 説 明 の あ と の タ グ セ ク シ ョ ン だ け に 置 く こ と が で き ま す 。 こ の タ グ は 、 @tag の よ う に 中 括 弧 で 囲 み ま せ ん 。

• イ ン ラ イ ン タ グ - コ メ ン ト の 説 明 内 ま た は ス タ ン ド ア ロ ン タ グ の コ メ ン ト 中 の 任 意 の 場 所 に 置 く こ と が で き ま す 。 イ ン ラ イ ン タ グ は 、 {@tag} の よ う に 中 括 弧 で 囲 み ま す 。

今 後 の リ リ ー ス で 導 入 さ れ る タ グ に つ い て は 、 「 Proposed Javadoc Tags」 を 参 照 し て く だ さ い 。

現 時 点 で 有 効 な タ グ を 以 下 に 示 し ま す 。

カ ス タ ム タ グ に つ い て は 、 −tag オ プ シ ョ ン を 参 照 し て く だ さ い 。
@author name-text

−author オ プ シ ョ ン が 使 わ れ て い る 場 合 、 生 成 さ れ る ド キ ュ メ ン ト に 、 指 定 さ れ た name-text を 持 つ Author エ ン ト リ を 追 加 し ま す 。 1 つ の doc コ メ ン ト に 複 数 の @author タ グ を 含 め る こ と が で き ま す 。 @author タ グ ご と に 1 つ 、 ま た は タ グ ご と に 複 数 の 名 前 を 指 定 で き ま す 。 前 者 の 場 合 は 、 javadoc ツ ー ル は 、 名 前 と 名 前 の 間 に コ ン マ (,) と ス ペ ー ス を 挿 入 し ま す 。 後 者 の 場 合 、 テ キ ス ト 全 体 が 解 析 さ れ る こ と な く 生 成 さ れ る ド キ ュ メ ン ト に コ ピ ー さ れ る だ け で す 。 こ の た め 、 コ ン マ 以 外 の 現 地 仕 様 の 名 前 区 切 り 文 字 を 使 う 場 合 は 、 1 行 に 複 数 の 名 前 を 指 定 し ま す 。

@deprecated deprecated-text

こ の API は (動 作 は す る が ) 使 用 す べ き で な い こ と を 示 す コ メ ン ト を 追 加 し ま す 。 javadoc
は 、 deprecated-text を 説 明 の 前 に 移 動 し て イ タ リ ッ ク に し 、 そ の 前 に ボ ー ル ド の 警 告 「 推 奨 さ れ ま せ ん 。 」 を 追 加 し ま す 。

deprecated-text の 最 初 の 文 で は 、 少 な く と も ユ ー ザ に ど の よ う な と き に そ の API が 推 奨 さ れ な い か 、 お よ び そ れ に 代 わ る API を 提 示 す る 必 要 が あ り ま す 。 javadoc は 、 最 初 の 文 だ け を 要 約 セ ク シ ョ ン と 索 引 に コ ピ ー し ま す 。 あ と に 続 く 文 で 、 な ぜ そ の API が 推 奨 さ れ な い か を 説 明 す る こ と も で き ま す 。 代 わ り の API を 指 し 示 す {@link} タ グ ( javadoc 1.2 以 降 の 場 合 ) を 含 め る 必 要 が あ り ま す 。

/**
* @deprecated As of JDK 1.1, replaced by
* {@link #setBounds(int,int,int,int)}
*/

推 奨 さ れ な い タ グ に つ い て の 詳 細 は 、 「 @deprecated タ グ 」 を 参 照 し て く だ さ い 。
{@docRoot}

生 成 さ れ た 任 意 の ペ ー ジ を 起 点 と し た 、 ド キ ュ メ ン ト の (出 力 先 ) ル ー ト デ ィ レ ク ト リ の 相 対 パ ス を 表 し ま す 。 こ の タ グ は 、 著 作 権 ペ ー ジ ま た は 会 社 の ロ ゴ な ど 、 生 成 さ れ る す べ て の ペ ー ジ か ら 参 照 す る フ ァ イ ル を 取 り 込 む と き に 使 い ま す 。 通 常 は 、 各 ペ ー ジ の 最 下 部 か ら 著 作 権 ペ ー ジ に リ ン ク し ま す 。

こ の {@docRoot} タ グ は 、 コ マ ン ド 行 お よ び doc コ メ ン ト で 使 う こ と が で き ま す 。

javadoc −bottom ’<a href="{@docRoot}/copyright.html">Copyright</a>’

javadoc −bottom ’<a
href="{@docRoot}/copyright.html">Copyright</a>’

注 - Makefile の 中 で {@docRoot}を こ の よ う に 利 用 す る 場 合 、 一 部 の Makefile プ ロ グ ラ ム で は 、 中 括 弧 { } 文 字 を エ ス ケ ー プ す る 必 要 が あ り ま す 。 た と え ば 、 Inprise MAKE バ ー ジ ョ ン 5.2 を Windows 上 で 実 行 す る 場 合 は 、 {{@docRoot}} の よ う に 、 中 括 弧 を 二 重 に す る 必 要 が あ り ま す 。 さ ら に 、 −bottom な ど の オ プ シ ョ ン に 対 す る 引 数 を 、 単 一 引 用 符 で は な く 、 二 重 引 用 符 で 囲 む 必 要 が あ り ま す 。 href 引 数 の 値 を 囲 む 引 用 符 は 省 略 し ま す 。

/**
* See the <a href="{@docRoot}/copyright.html">Copyright</a>.
*/

こ の タ グ が 必 要 な 理 由 は 、 生 成 さ れ る ド キ ュ メ ン ト が 、 サ ブ パ ッ ケ ー ジ と 同 じ 階 層 の デ ィ レ ク ト リ に 格 納 さ れ る た め で す 。 た と え ば 、 次 の よ う に 指 定 し ま す 。

<a href="{@docRoot}/copyright.html">

次 の よ う に 解 決 さ れ ま す 。

<a href="../../copyright.html"> ... java/lang/Object.java の 場 合

お よ び

<a href="../../../copyright.html"> ... java/lang/ref/Reference.java の 場 合

@exception class-name description

@exception タ グ は 、 @throws と 同 義 で す 。

{@inheritDoc}

最 も 近 い ス ー パ ー ク ラ ス か ら 現 在 の ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト に 、 ド キ ュ メ ン ト を 継 承 し ま す 。 こ の 機 能 に よ り 、 コ メ ン ト は 継 承 ツ リ ー の 上 位 に 移 動 し 、 開 発 者 は コ ピ ー し た テ キ ス ト に 記 述 を 追 加 す る こ と が で き ま す 。 コ メ ン ト の 継 承 も あ わ せ て 参 照 し て く だ さ い 。

こ の タ グ は 次 の 2 つ の 位 置 に 配 置 で き ま す 。

{@link " package.class#member label" }

参 照 ク ラ ス の 、 指 定 さ れ た 名 前 を 持 つ パ ッ ケ ー ジ 、 ク ラ ス 、 ま た は メ ン バ に つ い て の ド キ ュ メ ン ト を 指 す イ ン ラ イ ン リ ン ク を 、 表 示 テ キ ス ト label と と も に 挿 入 し ま す 。

こ の タ グ は 、 @see タ グ と よ く 似 て い ま す 。 ど ち ら の タ グ も 、 package.class#member お よ び label の 参 照 の 仕 方 が 同 じ で 、 有 効 な 構 文 も ま っ た く 同 じ で す 。 大 き な 違 い は 、 {@link} は 、 リ ン ク を [関 連 項 目 ] セ ク シ ョ ン に 置 く の で は な く 、 イ ン ラ イ ン リ ン ク を 生 成 す る と い う こ と で す 。 ま た 、 イ ン ラ イ ン テ キ ス ト の ほ か の 部 分 と 区 別 す る た め に 、 {@link} タ グ の 最 初 と 最 後 に 中 括 弧 を 記 述 し ま す 。 ラ ベ ル の 中 で 「 }」 を 使 う 必 要 が あ る 場 合 は 、 HTML エ ン テ ィ テ ィ の 「 &#125;」 を 使 い ま す 。

1 つ の 文 の 中 で 使 用 で き る {@link} タ グ の 数 に 制 限 は あ り ま せ ん 。 こ の タ グ は 、 ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト の 説 明 部 分 、 ま た は @deprecated 、 @return 、 @param な ど の 任 意 の タ グ の テ キ ス ト 部 分 で 使 う こ と が で き ま す 。

た と え ば 、 次 の コ メ ン ト で は 、 getComponentAt(int, int) メ ソ ッ ド を 参 照 し て い ま す 。

Use the {@link #getComponentAt(int, int) getComponentAt} method.

標 準 ド ッ ク レ ッ ト で は 、 上 記 の コ メ ン ト か ら 次 の HTML が 生 成 さ れ ま す (こ の コ メ ン ト が 同 じ パ ッ ケ ー ジ の 別 の ク ラ ス を 参 照 し て い る 場 合 )。

Use the
<a href="Component.html#getComponentAt(int, int)">\
getComponentAt</a>method.

こ の HTML は 、 Web ペ ー ジ 上 で は 次 の よ う に 表 示 さ れ ま す 。

Use the getComponentAt method.

{@link} を 、 ド キ ュ メ ン ト 化 の 対 象 に し て い な い ク ラ ス に ま で 拡 張 す る に は 、 −link オ プ シ ョ ン を 使 用 し ま す 。

{@linkplain " package.class#member label"}

リ ン ク の ラ ベ ル が コ ー ド フ ォ ン ト で は な く プ レ ー ン テ キ ス ト で 表 示 さ れ て い る 点 以 外 は 、 {@link} と 同 じ で す 。 ラ ベ ル が プ レ ー ン テ キ ス ト で 記 述 さ れ て い る 場 合 に 便 利 で す 。 次 の 例 を 参 照 し て く だ さ い 。

Refer to {@linkplain add() the overridden method}.

こ れ は 以 下 の よ う に 表 示 さ れ ま す 。

Refer to the overridden method.
@param parameter-name description

Parameters セ ク シ ョ ン に パ ラ メ ー タ を 追 加 し ま す 。 説 明 は 次 の 行 に 続 け て 記 述 で き ま す 。

@return description

description で 指 定 さ れ た テ キ ス ト を 持 つ 戻 り 値 セ ク シ ョ ン を 追 加 し ま す 。 テ キ ス ト で は 、 戻 り 値 の 型 と 取 り 得 る 値 の 範 囲 に つ い て 記 述 す る 必 要 が あ り ま す 。

@see reference

reference を 指 す リ ン ク ま た は テ キ ス ト エ ン ト リ を 持 つ [関 連 項 目 ] 見 出 し を 追 加 し ま す 。 doc コ メ ン ト に は 任 意 の 数 の @see タ グ を 含 め る こ と が で き 、 こ れ ら の タ グ は す べ て 同 じ 見 出 し の 下 に ま と め ら れ ま す 。 @see タ グ に は 次 の 3 つ の 形 式 が あ り ま す 。 3 番 目 が も っ と も 一 般 的 な 形 式 で す 。

@see string

string の テ キ ス ト エ ン ト リ を 追 加 し ま す 。 リ ン ク は 生 成 さ れ ま せ ん 。 string は 、 書 籍 、 ま た は URL で は ア ク セ ス で き な い 情 報 の 参 照 先 で す 。 javadoc ツ ー ル は 、 最 初 の 文 字 が 二 重 引 用 符 (") か ど う か を 調 べ て 、 上 の 2 つ の 形 式 と こ の 形 式 と を 区 別 し ま す 。 次 に 例 を 示 し ま す 。

@see "The Java Programming Language"

こ れ は 次 の よ う な テ キ ス ト を 生 成 し ま す 。

関 連 項 目 :
"The Java Programming Language"

@see <a href="URL#value">label</a>

URL#value で 定 義 さ れ た と お り に リ ン ク を 追 加 し ま す 。

URL#value は 、 相 対 URL ま た は 絶 対 URL で す 。 javadoc ツ ー ル は 、 最 初 の 文 字 と し て 、 小 な り 括 弧 (<) を 探 す こ と で 、 こ の リ ン ク を そ の 他 の 場 合 と 区 別 し ま す 。

@see <a href="spec.html#section">Java Spec</a>

こ れ は 次 の よ う な リ ン ク を 生 成 し ま す 。

関 連 項 目 :
Java Spec

@see package.class#member label

参 照 さ れ る Java 言 語 で 指 定 さ れ た 名 前 の ド キ ュ メ ン ト を 指 す 、 表 示 テ キ ス ト label を 持 つ リ ン ク を 追 加 し ま す 。 label は 省 略 可 能 で す 。 label を 省 略 し た 場 合 は 、 該 当 す る 名 前 が 適 切 に 短 く さ れ て (「 名 前 の 表 示 方 法 」 を 参 照 )、 表 示 テ キ ス ト と し て 代 わ り に 表 示 さ れ ま す 。 ラ ベ ル は 、 表 示 テ キ ス ト を 短 縮 す る 場 合 や 、 該 当 す る 名 前 と 異 な る 表 示 テ キ ス ト を 指 定 す る 場 合 に 使 い ま す 。

バ ー ジ ョ ン 1.2 で は 、 ラ ベ ル で は な く 、 名 前 だ け が HTML タ グ <code> に 囲 ま れ て 自 動 的 に 表 示 さ れ ま す 。 バ ー ジ ョ ン 1.2.2 以 降 は 、 <code> は 常 に 、 ラ ベ ル が 使 用 さ れ て い る か ど う か に か か わ ら ず 、 表 示 可 能 な テ キ ス ト を 囲 み ま す 。

例 -こ の 例 で は 、 Character ク ラ ス の @see タ グ が String ク ラ ス の equals メ ソ ッ ド を 参 照 し て い ま す 。 タ グ に は 、 名 前 String#equals(Object) と ラ ベ ル equals の 両 方 の 引 数 が 含 ま れ て い ま す 。

/**
* @see String#equals(Object) equals
*/

標 準 ド ッ ク レ ッ ト は 、 次 の よ う な HTML を 生 成 し ま す 。

<dl>
<dt><b>関 連 項 目 :</b>
<dd><a href="../../java/lang/String#equals\

(java.lang.Object)"><code>equals</code></a>
</dl>

こ れ は 、 ブ ラ ウ ザ で は 次 の よ う に 表 示 さ れ 、 ラ ベ ル が リ ン ク テ キ ス ト に な り ま す 。

関 連 項 目 :
equals

名 前 の 指 定 : こ の package.class#member の 名 前 は 、 java.lang.String#toUpperCase() の よ う に 完 全 指 定 す る こ と も 、 String#toUpperCase() や #toUpperCase() な ど の よ う に 完 全 指 定 し な い こ と も 可 能 で す 。 完 全 指 定 し な い 場 合 、 javadoc ツ ー ル は 、 通 常 の Java コ ン パ イ ラ の 検 索 順 序 で 検 索 を 行 い ま す 。 詳 細 は 、 以 下 の 「 @see の 検 索 順 序 」 を 参 照 し て く だ さ い 。 指 定 す る 名 前 で は 、 メ ソ ッ ド の 複 数 の 引 数 の 型 の 間 な ど 、 括 弧 内 に 空 白 を 含 め る こ と が で き ま す 。

短 い 部 分 修 飾 名 を 指 定 す る こ と の 利 点 は 、 入 力 す る 文 字 数 が 減 る こ と と 、 ソ ー ス コ ー ド が 読 み や す く な る こ と で す 。 以 下 の 表 に 示 す の は 、 さ ま ざ ま な 形 式 の 名 前 で す 。 Class に は ク ラ ス か イ ン タ フ ェ ー ス 、 Type に は ク ラ ス 、 イ ン タ フ ェ ー ス 、 配 列 、 ま た は 基 本 デ ー タ 型 、 method に は メ ソ ッ ド ま た は コ ン ス ト ラ ク タ を 指 定 で き ま す 。

上 の 表 に 対 す る 注 を 以 下 に 示 し ま す 。

@see の 検 索 順 序 : javadoc は 、 ソ ー ス フ ァ イ ル (.java)、 パ ッ ケ ー ジ フ ァ イ ル (package.html)、 ま た は 概 要 フ ァ イ ル (overview.html) 内 で 使 わ れ る @see タ グ を 処 理 し ま す 。 あ と の 2 つ の フ ァ イ ル で は 、 @see を 使 っ て 指 定 す る 名 前 を 完 全 修 飾 す る 必 要 が あ り ま す 。 ソ ー ス フ ァ イ ル で は 、 完 全 修 飾 名 と 部 分 修 飾 名 の ど ち ら を 指 定 す る こ と も で き ま す 。

javadoc ツ ー ル が 、 完 全 修 飾 さ れ て い な い .java フ ァ イ ル で @see タ グ を 見 つ け た 場 合 、 指 定 さ れ た 名 前 を Java コ ン パ イ ラ と 同 じ 順 序 で 検 索 し ま す 。 た だ し 、 javadoc ツ ー ル は 、 一 部 の 名 前 空 間 の あ い ま い さ は 検 出 し ま せ ん 。 こ れ は 、 javadoc ツ ー ル が 、 ソ ー ス コ ー ド に こ れ ら の エ ラ ー が 存 在 し て い な い こ と を 前 提 と し て 動 作 す る た め で す 。 検 索 順 序 は 、 「 Java Language Specification」 第 2 版 の 第 6 章 「 Names」 で 正 式 に 定 義 さ れ て い ま す 。 具 体 的 に は 、 検 索 は 次 の 順 序 で 行 わ れ ま す 。

javadoc ツ ー ル は 、 一 致 す る 名 前 が 見 つ か る ま で 、 各 ク ラ ス に つ い て 手 順 1 〜 3 を 繰 り 返 し て 検 索 を 続 け ま す 。 つ ま り 、 現 在 の ク ラ ス と そ の ク ラ ス を 囲 む ク ラ ス E を 検 索 し た あ と 、 E の ス ー パ ク ラ ス を 検 索 し 、 最 後 に E を 囲 む ク ラ ス を 検 索 し ま す 。 手 順 4 と 5 で は 、 javadoc ツ ー ル は 、 1 つ の パ ッ ケ ー ジ 内 で の ク ラ ス ま た は イ ン タ フ ェ ー ス の 検 索 を 、 な ん ら か の 決 ま っ た 順 序 で 行 う わ け で は あ り ま せ ん (こ の 検 索 順 序 は コ ン パ イ ラ に 依 存 し ま す )。 手 順 5 で は 、 javadoc ツ ー ル は 、 java.lang を 検 索 し ま す 。 こ れ は 、 java.lang が す べ て の プ ロ グ ラ ム に よ っ て 自 動 的 に イ ン ポ ー ト さ れ る た め で す 。

javadoc ツ ー ル は 、 必 ず し も サ ブ ク ラ ス を 検 索 す る わ け で は な く 、 Javadoc ツ ー ル の 実 行 中 に ほ か の パ ッ ケ ー ジ の ド キ ュ メ ン ト が 生 成 さ れ る 場 合 で も 、 ほ か の パ ッ ケ ー ジ の 検 索 は 行 い ま せ ん 。 た と え ば 、 @see タ グ が java.awt.event.KeyEvent ク ラ ス に あ っ て 、 java.awt パ ッ ケ ー ジ に あ る 名 前 を 参 照 す る 場 合 、 javadoc は 、 そ の ク ラ ス が イ ン ポ ー ト し な い 限 り そ の パ ッ ケ ー ジ を 検 索 し ま せ ん 。

名 前 の 表 示 方 法 : label が 省 略 さ れ た 場 合 は 、 package.class.member が 表 示 さ れ ま す 。 通 常 、 package.class.member は 、 現 在 の ク ラ ス お よ び パ ッ ケ ー ジ に 応 じ て 適 切 に 短 く さ れ ま す 。 「 短 く さ れ る 」 と は 、 javadoc ツ ー ル が 必 要 最 小 限 の 名 前 を 表 示 す る と い う こ と で す 。 た と え ば 、 String.toUpperCase() メ ソ ッ ド が 同 じ ク ラ ス の メ ン バ へ の 参 照 と 、 別 の ク ラ ス の メ ン バ へ の 参 照 を 含 ん で い る 場 合 、 ク ラ ス 名 は 後 者 の 場 合 だ け 表 示 さ れ ま す 。

@see の 例 : 右 側 の コ メ ン ト は 、 @see タ グ が java.applet.Applet: な ど の 別 の パ ッ ケ ー ジ の ク ラ ス 内 に あ る 場 合 に 名 前 が 表 示 さ れ る 方 法 を 示 し て い ま す 。

@see
を 、 ド キ ュ メ ン ト 化 の 対 象 に し て い な い ク ラ ス に ま で 拡 張 す る に は 、

−link オ プ シ ョ ン を 使 用 し ま す 。

@since since-text

生 成 さ れ る ド キ ュ メ ン ト に 、 指 定 さ れ た since-text を 持 つ [導 入 さ れ た バ ー ジ ョ ン ] 見 出 し を 追 加 し ま す 。 こ の テ キ ス ト に は 、 特 別 な 内 部 構 造 は あ り ま せ ん 。 こ の タ グ は 、 特 定 の 変 更 ま た は 機 能 が 、 since-text に よ っ て 指 定 さ れ た ソ フ ト ウ ェ ア の リ リ ー ス 以 来 、 継 続 し て 存 在 す る こ と を 意 味 し ま す 。 た と え ば 、 次 の と お り で す 。

@since 1.4

Java プ ラ ッ ト フ ォ ー ム の ソ ー ス コ ー ド の 場 合 、 こ の タ グ は 、 Java プ ラ ッ ト フ ォ ー ム API 仕 様 の バ ー ジ ョ ン を 示 し ま す 。 そ の 変 更 や 機 能 が リ フ ァ レ ン ス 実 装 に 追 加 さ れ た 時 期 を 示 す と は 限 り ま せ ん 。
@serial field-description|include|exclude

デ フ ォ ル ト の 直 列 化 可 能 フ ィ ー ル ド の doc コ メ ン ト で 使 用 し ま す 。

省 略 可 能 な field-description は 、 フ ィ ー ル ド の doc コ メ ン ト を 拡 張 し ま す 。 こ の 説 明 で は 、 フ ィ ー ル ド の 意 味 お よ び 取 り 得 る 値 の リ ス ト を 指 定 し な け れ ば な り ま せ ん 。 必 要 な 場 合 に は 、 複 数 の 行 に ま た が っ て 説 明 を 記 述 す る こ と が で き ま す 。 標 準 ド ッ ク レ ッ ト は 、 こ の 情 報 を 、 直 列 化 さ れ た 形 式 の ペ ー ジ に 追 加 し ま す 。

include と exclude 引 数 は 、 直 列 化 さ れ た 形 式 の ペ ー ジ に ク ラ ス ま た は パ ッ ケ ー ジ を 含 め る べ き か 、 あ る い は こ れ ら の 引 数 を 除 く べ き か を 指 定 し ま す 。 こ れ ら は 、 次 の よ う に 動 作 し ま す 。

例 : javax.swing パ ッ ケ ー ジ は 、 (package.html 内 で ) @serial exclude と マ ー ク さ れ ま す 。 public ク ラ ス で あ る java.sercurity.BasicPermission は 、 @serial exclude と マ ー ク さ れ ま す 。 package−private ク ラ ス で あ る java.util.PropertyPermissionCollection は 、 @serial include と マ ー ク さ れ ま す 。

ク ラ ス レ ベ ル の タ グ @serial は 、 パ ッ ケ ー ジ レ ベ ル の @serial を オ ー バ ー ラ イ ド し ま す 。

こ れ ら の タ グ の 使 用 法 に つ い て の 詳 細 と 使 用 例 は 、 「 Java オ ブ ジ ェ ク ト 直 列 化 仕 様 」 の 1.6 節 「 ク ラ ス の 直 列 化 可 能 な フ ィ ー ル ド お よ び デ ー タ の 文 書 化 」 を 参 照 し て く だ さ い 。 ま た 、 「 直 列 化 の FAQ」 も 参 照 し て く だ さ い 。 こ こ に は 、 「 −private ス イ ッ チ を 指 定 し な い で javadoc を 実 行 し た 場 合 、 private フ ィ ー ル ド に @serial タ グ が な い こ と に つ い て 警 告 が 表 示 さ れ る の は な ぜ か 」 と い う 質 問 と そ の 回 答 が あ り ま す 。

@serialField field-name field-type field-description

Serializable ク ラ ス の serialPersistentFields メ ン バ の ObjectStreamField コ ン ポ ー ネ ン ト を ド キ ュ メ ン ト 化 し ま す 。 各 ObjectStreamField コ ン ポ ー ネ ン ト に 対 し て @serialField タ グ を 1 つ 使 う 必 要 が あ り ま す 。

@serialData data-description

data-description は 、 直 列 化 さ れ た 形 式 で の デ ー タ の 型 と 順 序 を 説 明 す る テ キ ス ト で す 。 こ の デ ー タ に は 、 特 に 、 writeObject メ ソ ッ ド に よ っ て 書 き 込 ま れ る 省 略 可 能 な デ ー タ 、 お よ び Externalizable.writeExternal メ ソ ッ ド に よ っ て 書 き 込 ま れ る す べ て の デ ー タ (基 底 ク ラ ス を 含 む ) が 含 ま れ ま す 。

@serialData タ グ は 、 writeObject、 readObject、 writeExternal、 お よ び readExternal の 各 メ ソ ッ ド の doc コ メ ン ト で 使 用 で き ま す 。

@throws class-name description

@throws タ グ と @exception タ グ は 同 義 で す 。 生 成 さ れ る ド キ ュ メ ン テ ー シ ョ ン に 、 class-name お よ び description テ キ ス ト を 持 つ [例 外 ] 小 見 出 し を 追 加 し ま す 。 class-name は 、 該 当 す る メ ソ ッ ド に よ っ て ス ロ ー さ れ る 可 能 性 の あ る 例 外 の 名 前 で す 。 こ の ク ラ ス が 完 全 修 飾 さ れ て い な い 場 合 、 javadoc ツ ー ル は 検 索 順 序 に 従 っ て ク ラ ス を 探 し ま す 。 ス ー パ ー ク ラ ス ま た は イ ン タ フ ェ ー ス 内 に ド キ ュ メ ン ト 化 さ れ て い る @throws タ グ の コ メ ン ト は 、 （ 1） サ ブ ク ラ ス の throws 節 で 宣 言 さ れ て い る 例 外 と （ 2） す べ て の 実 行 時 の 例 外 に 継 承 さ れ ま す 。 こ う し た 例 外 が 存 在 し な い 場 合 、 ド キ ュ メ ン ト を 強 制 的 に 継 承 さ せ る に は 、 {@inheritDoc} を 使 用 し ま す 。

{@value}

static フ ィ ー ル ド の コ メ ン ト 内 で 使 用 す る と 、 定 数 の 値 を 表 示 し ま す 。 こ れ ら は 、 「 定 数 フ ィ ー ル ド 値 」 ペ ー ジ で 表 示 さ れ る 値 で す 。

@version version-text

−version オ プ シ ョ ン が 使 わ れ て い る 場 合 、 生 成 さ れ る ド キ ュ メ ン ト に 、 指 定 さ れ た version-text を 持 つ [バ ー ジ ョ ン ] 小 見 出 し を 追 加 し ま す 。 こ の テ キ ス ト に は 、 特 別 な 内 部 構 造 は あ り ま せ ん 。 1 つ の doc コ メ ン ト に 含 め る こ と の で き る @version タ グ は 1 つ 以 下 で す 。 通 常 、 バ ー ジ ョ ン は 、 該 当 す る ク ラ ス ま た は メ ン バ を 含 む ソ フ ト ウ ェ ア (Java 2 SDK な ど ) の バ ー ジ ョ ン を 指 し ま す 。

タ グ を 使 用 で き る 場 所
以 下 で は 、 タ グ を 使 用 で き る 場 所 に つ い て 説 明 し ま す 。 @see、 @link、 @since、 お よ び @deprecated の 4 つ の タ グ は 、 す べ て の doc コ メ ン ト で 使 用 で き ま す 。

概 要 ド キ ュ メ ン ト タ グ
概 要 タ グ は 、 概 要 ペ ー ジ の ド キ ュ メ ン ト コ メ ン ト (通 常 は overview.html と い う 名 前 の ソ ー ス フ ァ イ ル 内 に あ る ) で 使 用 で き る タ グ で す 。 ほ か の ド キ ュ メ ン ト コ メ ン ト と 同 様 に 、 こ れ ら の タ グ は 、 説 明 の あ と で 使 う 必 要 が あ り ま す 。

注 :バ ー ジ ョ ン 1.2 で は 、 概 要 ド キ ュ メ ン ト 内 の {@link} タ グ に バ グ が あ り ま す 。 テ キ ス ト は 適 切 に 表 示 さ れ ま す が 、 リ ン ク が 設 定 さ れ ま せ ん 。 現 在 の と こ ろ 、 {@docRoot} タ グ は 、 概 要 ド キ ュ メ ン ト 内 で は 動 作 し ま せ ん 。

パ ッ ケ ー ジ ド キ ュ メ ン ト タ グ
パ ッ ケ ー ジ タ グ は 、 パ ッ ケ ー ジ の ド キ ュ メ ン ト コ メ ン ト (package.html と い う 名 前 の ソ ー ス フ ァ イ ル に 存 在 ) で 使 用 で き る タ グ で す 。 こ こ で 使 用 で き る @serial タ グ は 、 include ま た は exclude 引 数 を 指 定 し た も の だ け で す 。

ク ラ ス お よ び イ ン タ フ ェ ー ス ド キ ュ メ ン ト タ グ
次 に 示 す の は 、 ク ラ ス ま た は イ ン タ フ ェ ー ス の ド キ ュ メ ン ト コ メ ン ト で 使 用 で き る タ グ で す 。 こ こ で 使 用 で き る @serial タ グ は 、 include ま た は exclude 引 数 を 指 定 し た も の だ け で す 。

次 は 、 ク ラ ス コ メ ン ト の 例 で す 。

/**
* A class representing a window on the screen.
* For example:
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @author Sami Shaio
* @version 1.12, 05/12/00
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
}

フ ィ ー ル ド ド キ ュ メ ン ト タ グ
次 に 示 す の は 、 フ ィ ー ル ド の ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト で 使 用 で き る タ グ で す 。

次 は 、 フ ィ ー ル ド コ メ ン ト の 例 で す 。

/**
* The X-coordinate of the component.
*
* @see #getLocation()
*/
int x = 1263732;

コ ン ス ト ラ ク タ お よ び メ ソ ッ ド ド キ ュ メ ン ト タ グ
次 に 、 コ ン ス ト ラ ク タ ま た は メ ソ ッ ド の ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト 内 で 表 示 で き る タ グ を 示 し ま す 。 た だ し 、 {@inheritDoc} は コ ン ス ト ラ ク タ 内 で は 表 示 で き ま せ ん 。

次 は メ ソ ッ ド の doc コ メ ン ト の 例 で す 。

/**
* Returns the character at the specified index. An index
* ranges from <code>0</code> to <code>length() - 1</code>.
*
* @param index the index of the desired character.
* @return the desired character.
* @exception StringIndexOutOfRangeException
* if the index is not in the range <code>0</code>
* to <code>length()-1</code>.
* @see java.lang.Character#charValue()
*/
public char charAt(int index) {
}

オ プ シ ョ ン

javadoc ツ ー ル は 、 ド ッ ク レ ッ ト を 使 っ て 出 力 を 決 定 し ま す 。 javadoc ツ ー ル は 、 −doclet オ プ シ ョ ン で カ ス タ ム ド ッ ク レ ッ ト が 指 定 さ れ て い る 場 合 以 外 は 、 デ フ ォ ル ト の 標 準 ド ッ ク レ ッ ト を 使 い ま す 。 javadoc ツ ー ル に は 、 任 意 の ド ッ ク レ ッ ト と と も に 使 用 で き る コ マ ン ド 行 オ プ シ ョ ン が あ り ま す 。 こ れ ら の オ プ シ ョ ン に つ い て は 、 後 述 の 「 javadoc の オ プ シ ョ ン 」 で 説 明 し ま す 。 標 準 ド ッ ク レ ッ ト で は 、 こ の ほ か に 、 い く つ か の 追 加 の コ マ ン ド 行 オ プ シ ョ ン が 提 供 さ れ ま す 。 こ れ ら の オ プ シ ョ ン に つ い て は 、 後 述 の 「 標 準 ド ッ ク レ ッ ト が 提 供 す る オ プ シ ョ ン 」 で 説 明 し ま す 。 ど の オ プ シ ョ ン 名 も 大 文 字 と 小 文 字 を 区 別 し ま せ ん 。 た だ し 、 オ プ シ ョ ン の 引 数 で は 大 文 字 と 小 文 字 が 区 別 さ れ る こ と が あ り ま す 。

オ プ シ ョ ン を 以 下 に 示 し ま す 。

Javadoc の オ プ シ ョ ン
−overview path/filename

javadoc に 対 し て 、 path/filename で 指 定 さ れ た 「 ソ ー ス 」 フ ァ イ ル か ら 概 要 ド キ ュ メ ン ト 用 の テ キ ス ト を 取 得 し 、 概 要 ペ ー ジ (overview-summary.html) に 配 置 す る こ と を 指 示 し ま す 。 path/filename は 、 −sourcepath へ の 相 対 パ ス で す 。

filename と path に は 、 そ れ ぞ れ 任 意 の 名 前 と 場 所 を 指 定 で き ま す が 、 通 常 は 、 overview.html と い う 名 前 を 付 け て 、 ソ ー ス ツ リ ー 内 の 最 上 位 の パ ッ ケ ー ジ デ ィ レ ク ト リ を 含 む デ ィ レ ク ト リ に 配 置 し ま す 。 こ の 場 所 で は 、 −sourcepath が こ の フ ァ イ ル を 指 す の で 、 パ ッ ケ ー ジ を ド キ ュ メ ン ト 化 す る 際 に path が 必 要 あ り ま せ ん 。 た と え ば 、 java.lang パ ッ ケ ー ジ の ソ ー ス ツ リ ー が /src/classes/java/lang/ の 場 合 、 概 要 フ ァ イ ル を /src/classes/overview.html に 配 置 で き ま す 。 「 使 用 例 」 を 参 照 し て く だ さ い 。

path/filename で 指 定 す る フ ァ イ ル に つ い て は 、 「 概 要 コ メ ン ト フ ァ イ ル 」 を 参 照 し て く だ さ い 。

概 要 ペ ー ジ が 作 成 さ れ る の は 、 javadoc に 2 つ 以 上 の パ ッ ケ ー ジ 名 を 渡 し た 場 合 だ け で す 。 詳 細 は 、 「 HTML フ レ ー ム 」 節 を 参 照 し て く だ さ い 。

概 要 ペ ー ジ の タ イ ト ル は 、 −doctitle に よ っ て 設 定 さ れ ま す 。

−public

public な ク ラ ス と メ ン バ だ け を 表 示 し ま す 。

−protected

protected お よ び public な ク ラ ス と メ ン バ だ け を 表 示 し ま す 。 こ れ は デ フ ォ ル ト の 動 作 で す 。

−package

パ ッ ケ ー ジ 、 お よ び protected と public な ク ラ ス と メ ン バ だ け を 表 示 し ま す 。

−private

す べ て の ク ラ ス と メ ン バ を 表 示 し ま す 。

−doclet class

ド キ ュ メ ン ト の 生 成 に 使 う ド ッ ク レ ッ ト を 起 動 す る た め の ク ラ ス フ ァ イ ル を 指 定 し ま す 。 完 全 指 定 の 名 前 を 指 定 し て く だ さ い 。 ド ッ ク レ ッ ト で は 、 出 力 の 内 容 と 形 式 を 定 義 し ま す 。 −doclet オ プ シ ョ ン が 使 わ れ て い な い 場 合 、 javadoc は 標 準 ド ッ ク レ ッ ト を 使 っ て デ フ ォ ル ト の HTML 形 式 を 生 成 し ま す 。 こ の ク ラ ス に は 、 start(Root) メ ソ ッ ド が 含 ま れ て い な け れ ば な り ま せ ん 。 こ の 起 動 ク ラ ス へ の パ ス は 、 −docletpath オ プ シ ョ ン に よ っ て 定 義 さ れ ま す 。

た と え ば 、 MIF ド ッ ク レ ッ ト を 呼 び 出 す に は 、 次 の よ う に 指 定 し ま す 。

-doclet com.sun.tools.doclets.mif.MIFDoclet

−docletpath classpathlist

−doclet オ プ シ ョ ン で 指 定 さ れ て い る ド ッ ク レ ッ ト ク ラ ス フ ァ イ ル 、 お よ び そ れ に 依 存 す る jar フ ァ イ ル へ の パ ス を 指 定 し ま す 。 起 動 ク ラ ス フ ァ イ ル が jar フ ァ イ ル 内 に あ る 場 合 、 例 に 従 っ て 、 そ の jar フ ァ イ ル へ の パ ス を 指 定 し ま す 。 絶 対 パ ス 、 ま た は 現 在 の デ ィ レ ク ト リ か ら の 相 対 パ ス を 指 定 で き ま す 。 classpathlist に は 、 複 数 の パ ス ま た は jar フ ァ イ ル を 含 め る こ と が で き ま す 。 そ の 場 合 、 各 パ ス ま た は jar フ ァ イ ル を コ ロ ン (:)で 区 切 り ま す 。 目 的 の ド ッ ク レ ッ ト の 開 始 ク ラ ス が す で に 検 索 パ ス 内 に あ る 場 合 は 、 こ の オ プ シ ョ ン は 不 要 で す 。

次 の 例 の jar フ ァ イ ル へ の パ ス に は 、 ド ッ ク レ ッ ト の 開 始 ク ラ ス フ ァ イ ル が 含 ま れ て い ま す 。 jar フ ァ イ ル 名 が 含 ま れ て い る 点 に 注 意 し て く だ さ い 。

−docletpath /home/user/mifdoclet/lib/mifdoclet.jar

次 は ド ッ ク レ ッ ト の 開 始 ク ラ ス フ ァ イ ル の パ ス の 例 で す 。 ク ラ ス フ ァ イ ル 名 が 省 略 さ れ て い る こ と に 注 意 し て く だ さ い 。

−docletpath /home/user/mifdoclet/classes/com/sun/tools/doclets/mif/

−sourcepath sourcepathlist

javadoc コ マ ン ド に パ ッ ケ ー ジ 名 ま た は −subpackages を 渡 す 際 に 、 ソ ー ス フ ァ イ ル (.java) 検 索 用 の パ ス を 指 定 し ま す 。 sourcepathlist に は 、 コ ロ ン (:) で 区 切 っ た 複 数 の パ ス を 含 め る こ と が で き ま す 。 Javadoc ツ ー ル は 、 指 定 さ れ た パ ス 以 下 の す べ て の サ ブ デ ィ レ ク ト リ を 検 索 し ま す 。 こ の オ プ シ ョ ン を 使 っ て 、 ド キ ュ メ ン ト 化 さ れ る ソ ー ス フ ァ イ ル の 位 置 だ け で な く 、 そ れ 自 体 は ド キ ュ メ ン ト 化 さ れ て い な い が 、 ド キ ュ メ ン ト 化 さ れ て い る ソ ー ス フ ァ イ ル か ら 継 承 さ れ た コ メ ン ト を も つ ソ ー ス フ ァ イ ル の 位 置 も 確 認 で き ま す 。

−sourcepath オ プ シ ョ ン は 、 javadoc コ マ ン ド を 使 っ て パ ッ ケ ー ジ 名 を 指 定 す る と き に だ け 使 用 で き 、 javadoc コ マ ン ド に 渡 さ れ る .java フ ァ イ ル は 検 索 で き な い こ と に 注 意 し て く だ さ い 。 .java フ ァ イ ル を 検 索 す る に は 、 そ の デ ィ レ ク ト リ に 移 動 す る か 、 各 フ ァ イ ル の 前 に そ の パ ス を 付 け ま す (「 1 つ 以 上 の パ ッ ケ ー ジ の ド キ ュ メ ン ト 化 」 を 参 照 )。 −sourcepath が 省 略 さ れ た 場 合 は 、 javadoc は ク ラ ス パ ス を 使 っ て ソ ー ス フ ァ イ ル を 検 索 し ま す ( −classpath を 参 照 )。 し た が っ て 、 −sourcepath の デ フ ォ ル ト は −classpath の 値 で す 。 -classpath を 省 略 し て パ ッ ケ ー ジ 名 を javadoc に 渡 し た 場 合 、 javadoc は 、 ソ ー ス フ ァ イ ル の 現 在 の デ ィ レ ク ト リ (お よ び サ ブ デ ィ レ ク ト リ ) を 検 索 し ま す 。

sourcepathlist で は 、 ド キ ュ メ ン ト 化 す る パ ッ ケ ー ジ 名 の ソ ー ス ツ リ ー の ル ー ト デ ィ レ ク ト リ を 設 定 し ま す 。 た と え ば 、 ソ ー ス フ ァ イ ル が 次 の 場 所 に あ る com.mypackage と い う 名 前 の パ ッ ケ ー ジ を ド キ ュ メ ン ト 化 す る と し ま す 。

/home/user/src/com/mypackage/*.java

こ の 場 合 、 次 の よ う に し て ソ ー ス パ ス を /home/user/src 、 つ ま り com.mypackage を 含 む デ ィ レ ク ト リ に 指 定 し 、 そ れ か ら パ ッ ケ ー ジ 名 com.mypackage を 指 定 し ま す 。

example% javadoc −sourcepath /home/user/src/ com.mypackage

こ れ は 、 ソ ー ス パ ス の 値 と パ ッ ケ ー ジ 名 を つ な げ て 、 ド ッ ト を ス ラ ッ シ ュ (/) に 変 え る と 、 以 下 の パ ッ ケ ー ジ の フ ル パ ス に な る こ と に 注 目 す る と 覚 え や す い で し ょ う 。

/home/user/src/com/mypackage

2 つ の ソ ー ス パ ス を 指 定 す る に は 、 次 の よ う に し ま す 。

example% javadoc −sourcepath /home/user/src/:/home/user2/src com.mypackage

−classpath classpathlist

javadoc が 参 照 さ れ る ク ラ ス の 検 索 を 行 う パ ス を 指 定 し ま す 。 参 照 さ れ る ク ラ ス (.class) と は 、 ド キ ュ メ ン ト 化 さ れ る ク ラ ス と そ れ ら の ク ラ ス に よ っ て 参 照 さ れ る 任 意 の ク ラ ス の こ と で す 。 javadoc は 、 指 定 さ れ た パ ス 以 下 の す べ て の サ ブ デ ィ レ ク ト リ で 検 索 を 行 い ま す 。 classpathlist に は 、 パ ス 間 を コ ロ ン (:) で 区 切 っ て 複 数 の パ ス を 含 め る こ と が で き ま す 。 javadoc ツ ー ル は 、 指 定 さ れ た パ ス 以 下 の す べ て の サ ブ デ ィ レ ク ト リ を 検 索 し ま す 。 classpathlist の 指 定 に つ い て は 、 ク ラ ス パ ス の ド キ ュ メ ン ト を 参 照 し て く だ さ い 。

−sourcepath を 省 略 し た 場 合 は 、 javadoc ツ ー ル は 、 ク ラ ス フ ァ イ ル (下 位 互 換 用 ) と と も に 、 −classpath を 使 っ て ソ ー ス フ ァ イ ル を 検 索 し ま す 。 こ の た め 、 異 な る パ ス 内 の ソ ー ス フ ァ イ ル お よ び ク ラ ス フ ァ イ ル を 検 索 す る 場 合 は 、 −sourcepath と −classpath の 両 方 を 使 い ま す 。

た と え ば 、 com.mypackage を ド キ ュ メ ン ト 化 し た い 場 合 に 、 パ ッ ケ ー ジ の ク ラ ス が デ ィ レ ク ト リ /home/user/src/com/mypackage に あ り 、 こ の パ ッ ケ ー ジ が /home/user/lib 内 の ラ イ ブ ラ リ を 使 う 場 合 は 、 次 の よ う に 指 定 し ま す 。

example% javadoc −classpath /home/user/lib −sourcepath \
/home/user/src com.mypackage

ほ か の ツ ー ル と 同 様 に 、 −classpath を 指 定 し な い 場 合 は 、 CLASSPATH 環 境 変 数 が 設 定 さ れ て い れ ば 、 javadoc ツ ー ル は こ の 環 境 変 数 を 使 い ま す 。 ど ち ら も 設 定 さ れ て い な い 場 合 は 、 javadoc ツ ー ル は 現 在 の デ ィ レ ク ト リ で ク ラ ス を 検 索 し ま す 。

javadoc ツ ー ル が 拡 張 機 能 ク ラ ス お よ び ブ ー ト ス ト ラ ッ プ ク ラ ス と 通 信 す る 際 に 、 -classpath を 使 っ て ユ ー ザ ク ラ ス を 検 索 す る 方 法 に つ い て の 詳 細 は 、 「 ク ラ ス の 検 索 方 法 」 を 参 照 し て く だ さ い 。

−bootclasspath classpathlist

ブ ー ト ク ラ ス が 存 在 す る パ ス を 指 定 し ま す 。 ブ ー ト ク ラ ス と は 、 Java コ ア ク ラ ス の こ と で す 。 bootclasspath は 、 javadoc ツ ー ル が ソ ー ス フ ァ イ ル と ク ラ ス フ ァ イ ル を 探 す と き に 使 う 検 索 パ ス の 一 部 で す 。 詳 細 は 、 「 Javac と Javadoc が ク ラ ス を 検 索 す る 方 法 」 を 参 照 し て く だ さ い 。 classpathlist 内 の 複 数 の ク ラ ス パ ス リ ス ト は 、 コ ロ ン (:) で 区 切 り ま す 。

−extdirs dirlist

拡 張 機 能 ク ラ ス が 存 在 す る デ ィ レ ク ト リ を 指 定 し ま す 。 拡 張 機 能 ク ラ ス は 、 Java 拡 張 機 能 機 構 を 使 う す べ て の ク ラ ス で す 。 拡 張 機 能 デ ィ レ ク ト リ ( extdirs ) は 、 javadoc ツ ー ル が ソ ー ス フ ァ イ ル と ク ラ ス フ ァ イ ル を 探 す と き に 使 う 検 索 パ ス の 一 部 で す 。 詳 細 は 、 上 の −classpath を 参 照 し て く だ さ い 。 dirlist 内 の 複 数 の デ ィ レ ク ト リ は 、 コ ロ ン (:) で 区 切 り ま す 。

−verbose

javadoc の 実 行 中 に 詳 細 な メ ッ セ ー ジ を 表 示 し ま す 。 冗 長 オ プ シ ョ ン を 指 定 し な い 場 合 は 、 ソ ー ス フ ァ イ ル の ロ ー ド 時 、 ド キ ュ メ ン ト の 生 成 時 (ソ ー ス フ ァ イ ル ご と に 1 つ の メ ッ セ ー ジ )、 お よ び ソ ー ト 時 に メ ッ セ ー ジ が 表 示 さ れ ま す 。 冗 長 オ プ シ ョ ン を 指 定 し た 場 合 は 、 各 java ソ ー ス フ ァ イ ル の 解 析 に 要 し た ミ リ 秒 数 な ど の 追 加 メ ッ セ ー ジ を 表 示 し ま す 。

−locale language_country_variant

重 要 : −locale オ プ シ ョ ン は 、 標 準 ド ッ ク レ ッ ト や そ の 他 の ド ッ ク レ ッ ト に よ っ て 提 供 さ れ る オ プ シ ョ ン よ り も 前 に (左 側 に ) 指 定 す る 必 要 が あ り ま す 。 そ う で な け れ ば 、 ナ ビ ゲ ー シ ョ ン バ ー は 英 語 で 表 示 さ れ ま す 。 順 序 に 依 存 す る コ マ ン ド 行 オ プ シ ョ ン は 、 こ の オ プ シ ョ ン の み で す 。

javadoc が ド キ ュ メ ン ト を 生 成 す る と き に 使 う ロ ケ ー ル を 指 定 し ま す 。 引 数 に は 、 java.util.Locale の ド キ ュ メ ン ト で 説 明 さ れ て い る ロ ケ ー ル を 指 定 し ま す 。 た と え ば 、 en_US (英 語 、 米 国 )、 en_US_WIN (Windows で 使 わ れ る 英 語 ) な ど を 指 定 し ま す 。

ロ ケ ー ル を 指 定 す る と 、 javadoc は 指 定 さ れ た ロ ケ ー ル の リ ソ ー ス フ ァ イ ル を 選 択 し て メ ッ セ ー ジ (ナ ビ ゲ ー シ ョ ン バ ー 、 リ ス ト と 表 の 見 出 し 、 ヘ ル プ フ ァ イ ル の 目 次 、 stylesheet.css の コ メ ン ト な ど の 文 字 列 ) に 使 い ま す 。 ま た 、 ア ル フ ァ ベ ッ ト 順 に ソ ー ト さ れ る リ ス ト の ソ ー ト 順 、 お よ び 最 初 の 文 の 末 尾 を 決 定 す る 文 の 区 切 り 文 字 も 、 指 定 し た ロ ケ ー ル に よ っ て 決 ま り ま す 。 こ の オ プ シ ョ ン は 、 ド キ ュ メ ン ト 化 さ れ る ク ラ ス の ソ ー ス フ ァ イ ル 内 で 指 定 さ れ て い る doc コ メ ン ト テ キ ス ト の ロ ケ ー ル を 決 定 す る も の で は あ り ま せ ん 。

−encoding name

ソ ー ス フ ァ イ ル の エ ン コ ー デ ィ ン グ 名 (EUCJIS/SJIS な ど ) を 指 定 し ま す 。 こ の オ プ シ ョ ン が 指 定 さ れ て い な い 場 合 は 、 プ ラ ッ ト フ ォ ー ム の デ フ ォ ル ト コ ン バ ー タ が 使 わ れ ま す 。

example% javadoc −J−Xmx32m −J−Xms32m com.mypackage

使 用 し て い る javadoc の バ ー ジ ョ ン を 確 認 す る に は 、 次 の よ う に java の 「 -version」 オ プ シ ョ ン を 呼 び 出 し ま す 。

example% javadoc -J-version
java version "1.2"
Classic VM (build JDK-1.2-V, green threads, sunwjit)

(標 準 ド ッ ク レ ッ ト の バ ー ジ ョ ン 番 号 は 出 力 ス ト リ ー ム に 表 示 さ れ ま す 。 )

標 準 ド ッ ク レ ッ ト が 提 供 す る オ プ シ ョ ン
−d directory

生 成 さ れ た HTML フ ァ イ ル を 保 存 す る デ ィ レ ク ト リ を 指 定 し ま す (d は 「 生 成 先 (destination)」 の 意 味 )。 こ の オ プ シ ョ ン を 省 略 す る と 、 生 成 さ れ た フ ァ イ ル は 現 在 の デ ィ レ ク ト リ に 保 存 さ れ ま す 。 値 directory に は 、 絶 対 デ ィ レ ク ト リ ま た は 現 在 の 作 業 デ ィ レ ク ト リ か ら の 相 対 デ ィ レ ク ト リ を 指 定 で き ま す 。 1.4 で は 、 javadoc の 実 行 時 に 自 動 的 に 生 成 先 デ ィ レ ク ト リ が 作 成 さ れ ま す 。

た と え ば 、 次 の 例 は 、 com.mypackage パ ッ ケ ー ジ の ド キ ュ メ ン ト を 生 成 し 、 結 果 を /home/user/doc/ デ ィ レ ク ト リ に 保 存 し ま す 。

example% javadoc −d /home/user/doc com.mypackage

た と え ば 、 String に つ い て 、 [使 用 ] ペ ー ジ に 何 が 表 示 さ れ る か を 見 て み ま し ょ う 。 java.awt.Font ク ラ ス の getName() メ ソ ッ ド は 、 String 型 を 返 し ま す 。 こ の た め 、 getName() は String を 使 う の で 、 [使 用 ] ペ ー ジ の String で こ の メ ソ ッ ド を 見 つ け る こ と が で き ま す 。

こ の ペ ー ジ で は API の 使 用 だ け が ド キ ュ メ ン ト 化 さ れ 、 実 装 は ド キ ュ メ ン ト 化 さ れ ま せ ん 。 あ る メ ソ ッ ド が 実 装 内 に String を 使 っ て い る が 、 引 数 と し て 文 字 列 を と っ た り 、 文 字 列 を 返 し た り し な い 場 合 は 、 String の 「 使 用 」 と は み な さ れ ま せ ん 。

生 成 さ れ た [使 用 ] ペ ー ジ に ア ク セ ス す る に は 、 目 的 の ク ラ ス ま た は パ ッ ケ ー ジ を 表 示 し て 、 ナ ビ ゲ ー シ ョ ン バ ー の [使 用 ] リ ン ク を ク リ ッ ク し ま す 。

−version

生 成 さ れ る ド キ ュ メ ン ト に @version テ キ ス ト を 含 め ま す 。 こ の テ キ ス ト は 、 デ フ ォ ル ト で は 省 略 さ れ ま す 。 使 用 し て い る javadoc ツ ー ル の バ ー ジ ョ ン を 確 認 す る に は 、 J−version オ プ シ ョ ン を 使 用 し ま す 。

−author

生 成 さ れ る ド キ ュ メ ン ト に @author テ キ ス ト を 含 め ま す 。

−splitindex

索 引 フ ァ イ ル を ア ル フ ァ ベ ッ ト ご と に 複 数 の フ ァ イ ル に 分 割 し 、 文 字 ご と に 1 つ の フ ァ イ ル と 、 ア ル フ ァ ベ ッ ト 以 外 の 文 字 で 始 ま る 索 引 エ ン ト リ 用 の フ ァ イ ル を 1 つ 作 成 し ま す 。

−windowtitle title

HTML の <title> タ グ で 使 う タ イ ト ル を 指 定 し ま す 。 指 定 し た タ イ ト ル は 、 ウ ィ ン ド ウ タ イ ト ル と 、 該 当 す る ペ ー ジ に 対 し て 作 成 さ れ た ブ ラ ウ ザ の ブ ッ ク マ ー ク (よ く ア ク セ ス す る 場 所 ) に 表 示 さ れ ま す 。 タ イ ト ル に は HTML タ グ を 含 め な い で く だ さ い 。 タ イ ト ル に HTML タ グ が 含 ま れ て い る と 、 ブ ラ ウ ザ に よ る タ グ の 解 釈 が 不 適 切 に な る 可 能 性 が あ り ま す 。 title の 中 で 引 用 符 を 使 う 場 合 は 、 引 用 符 を エ ス ケ ー プ す る 必 要 が あ り ま す 。 -windowtitle が 省 略 さ れ て い る 場 合 、 javadoc ツ ー ル は こ の オ プ シ ョ ン の 代 わ り に -doctitle の 値 を 使 い ま す 。

example% javadoc -windowtitle "Java 2 Platform" com.mypackage

−doctitle title

概 要 フ ァ イ ル の 最 上 部 近 く に 配 置 す る タ イ ト ル を 指 定 し ま す 。 タ イ ト ル は 中 央 揃 え さ れ 、 レ ベ ル 1 の 見 出 し と し て 上 部 ナ ビ ゲ ー シ ョ ン バ ー の す ぐ 下 に 置 か れ ま す 。 title に は 、 HTML タ グ と 空 白 を 含 め る こ と が で き ま す が 、 こ れ ら を 含 め る 場 合 は 全 体 を 引 用 符 で 囲 ま な け れ ば な り ま せ ん 。 title の 中 で 引 用 符 を 使 う 場 合 は 、 引 用 符 を エ ス ケ ー プ す る 必 要 が あ り ま す 。

example% javadoc -doctitle "Java^{<font size=
TM</font>}" com.mypackage

−title title

こ の オ プ シ ョ ン は 、 現 在 は 存 在 し ま せ ん 。 javadoc 1.2 の ベ ー タ 版 に だ け 存 在 し ま し た 。 こ の オ プ シ ョ ン は 、 ウ ィ ン ド ウ タ イ ト ル で は な く ド キ ュ メ ン ト タ イ ト ル を 定 義 す る こ と を 明 確 に す る た め 、 −doctitle に 名 前 が 変 更 さ れ ま し た 。

−header header

各 出 力 フ ァ イ ル の 上 部 に 配 置 す る ヘ ッ ダ テ キ ス ト を 指 定 し ま す 。 ヘ ッ ダ は 、 上 部 ナ ビ ゲ ー シ ョ ン バ ー の 右 側 に 配 置 さ れ ま す 。 header に は 、 HTML タ グ と 空 白 を 含 め る こ と が で き ま す が 、 こ れ ら を 含 め る 場 合 は 全 体 を 引 用 符 で 囲 ま な け れ ば な り ま せ ん 。 header の 中 で 引 用 符 を 使 う 場 合 は 、 引 用 符 を エ ス ケ ー プ す る 必 要 が あ り ま す 。

−footer footer

各 出 力 フ ァ イ ル の 下 部 に 配 置 す る フ ッ タ テ キ ス ト を 指 定 し ま す 。 フ ッ タ は 、 下 部 ナ ビ ゲ ー シ ョ ン バ ー の 右 側 に 配 置 さ れ ま す 。 footer に は 、 HTML タ グ と 空 白 を 含 め る こ と が で き ま す が 、 こ れ ら を 含 め る 場 合 は 全 体 を 引 用 符 で 囲 ま な け れ ば な り ま せ ん 。 footer の 中 で 引 用 符 を 使 う 場 合 は 、 引 用 符 を エ ス ケ ー プ す る 必 要 が あ り ま す 。

−bottom text

各 出 力 フ ァ イ ル の 最 下 部 に 配 置 す る テ キ ス ト を 指 定 し ま す 。 こ の テ キ ス ト は 、 下 部 ナ ビ ゲ ー シ ョ ン バ ー の 下 の ペ ー ジ の 最 下 部 に 配 置 さ れ ま す 。 text に は 、 HTML タ グ と 空 白 を 含 め る こ と が で き ま す が 、 こ れ ら を 含 め る 場 合 は 全 体 を 引 用 符 で 囲 ま な け れ ば な り ま せ ん 。 text の 中 で 引 用 符 を 使 う 場 合 は 、 引 用 符 を エ ス ケ ー プ す る 必 要 が あ り ま す 。

−link extdocURL

javadoc ツ ー ル に よ り 生 成 さ れ た 既 存 の 外 部 参 照 ク ラ ス の ド キ ュ メ ン テ ー シ ョ ン へ の リ ン ク を 作 成 し ま す 。 引 数 は 1 つ で す 。

ド キ ュ メ ン ト を 任 意 の Web サ イ ト 上 の ド キ ュ メ ン ト に リ ン ク す る に は extdocURL の 絶 対 リ ン ク を 、 相 対 ロ ケ ー シ ョ ン だ け を 指 定 す る に は 相 対 リ ン ク を 使 用 で き ま す 。 相 対 リ ン ク を 使 用 す る 場 合 、 生 成 先 デ ィ レ ク ト リ (−d で 指 定 ) か ら の 相 対 パ ス を 、 リ ン ク 先 パ ッ ケ ー ジ が あ る デ ィ レ ク ト リ に 渡 す 必 要 が あ り ま す 。

通 常 、 絶 対 リ ン ク を 指 定 す る 場 合 は 、 http: リ ン ク を 使 用 し ま す 。 た だ し 、 Web サ ー バ を も た な い フ ァ イ ル シ ス テ ム に リ ン ク す る 場 合 は 、 file: リ ン ク を 使 用 で き ま す 。 た だ し 、 こ の 方 法 は 、 生 成 さ れ た ド キ ュ メ ン ト に ア ク セ ス し よ う と す る す べ て の ユ ー ザ が 同 じ フ ァ イ ル シ ス テ ム を 共 有 し て い る 場 合 以 外 は 使 用 し な い で く だ さ い 。

javadoc 実 行 時 に 複 数 の −link オ プ シ ョ ン を 指 定 し て 、 複 数 の ド キ ュ メ ン ト へ の リ ン ク を 作 成 す る こ と も で き ま す 。

−linkoffline ま た は −link の 選 択 − 現 在 実 行 中 の javadoc の 外 部 に あ る API ド キ ュ メ ン ト に リ ン ク す る と き 、 ど ち ら か の オ プ シ ョ ン を 使 用 し ま す 。

−link を 使 用 す る 場 合 : • 外 部 API ド キ ュ メ ン ト へ の 相 対 パ ス を 使 用 し て い る • 外 部 API ド キ ュ メ ン ト へ の 絶 対 URL を 使 用 し て い る
(プ ロ グ ラ ム が そ の URL に 接 続 し 、 読 み 取 り を 行 う こ と が シ ェ ル に よ っ て 許 可 さ れ て い る 場 合 )

−linkoffline を 使 用 す る 場 合 : • 外 部 API ド キ ュ メ ン ト へ の 絶 対 URL を 使 用 し て い る (プ ロ グ ラ ム が そ の URL に 接 続 し 、 読 み 取 り を 行 う こ と が シ ェ ル に よ っ て 許 可 さ れ て い な い 場 合 )。 こ の よ う な 状 況 は 、 リ ン ク 先 の ド キ ュ メ ン ト が フ ァ イ ア ウ ォ ー ル の 向 こ う 側 に あ る 場 合 に 発 生 し ま す 。

外 部 ド キ ュ メ ン ト へ の 絶 対 リ ン ク の 使 用 例 - java.lang、 java.io、 お よ び 他 の Java 2 プ ラ ッ ト フ ォ ー ム パ ッ ケ ー ジ (http://java.sun.com/j2se/1.4/docs/api) に リ ン ク し た い 場 合 が あ り ま す 。 次 の コ マ ン ド は 、 Java 2 プ ラ ッ ト フ ォ ー ム パ ッ ケ ー ジ へ の リ ン ク を 持 つ com.mypackage パ ッ ケ ー ジ の ド キ ュ メ ン ト を 生 成 し ま す 。 生 成 さ れ た ド キ ュ メ ン ト に は 、 た と え ば ク ラ ス ツ リ ー 内 の Object ク ラ ス へ の リ ン ク が 含 ま れ て い ま す (−sourcepath や −d な ど の 他 の オ プ シ ョ ン は 表 示 さ れ ま せ ん )。

% javadoc −link http://java.sun.com/j2se/1.4/docs/api com.mypackage

外 部 ド キ ュ メ ン ト へ の 相 対 リ ン ク の 使 用 例 - javadoc ツ ー ル の 異 な る 実 行 で 生 成 さ れ た ド キ ュ メ ン ト を 持 つ 2 つ の パ ッ ケ ー ジ が あ り 、 そ れ ら が 別 々 の 相 対 パ ス を も っ て い る と し ま す 。 こ の 例 で は 、 2 つ の パ ッ ケ ー ジ を com.apipackage (API)、 com.spipackage (SPI - Service Provide Interface) と し ま す 。 ド キ ュ メ ン ト の 置 き 場 所 は docs/api/com/apipackage お よ び docs/spi/com/spipackage で す 。 API パ ッ ケ ー ジ ド キ ュ メ ン ト は す で に 生 成 さ れ 、 ド キ ュ メ ン ト が 現 在 の デ ィ レ ク ト リ 内 に あ る 場 合 、 次 の よ う に 実 行 す る こ と で 、 API ド キ ュ メ ン ト に リ ン ク し た SPI パ ッ ケ ー ジ を ド キ ュ メ ン ト 化 で き ま す 。

% javadoc −d ./spi −link ../api com.spipackage

−link 引 数 が 生 成 先 デ ィ レ ク ト リ の 相 対 パ ス (docs/spi) で あ る こ と に 注 意 し て く だ さ い 。

詳 細 - −link オ プ シ ョ ン を 使 う と 、 コ ー ド か ら は 参 照 さ れ て い て も 、 Javadoc の 現 在 の 実 行 で は ド キ ュ メ ン ト 化 さ れ な い ク ラ ス に リ ン ク で き る よ う に な り ま す 。 リ ン ク か ら 有 効 な ペ ー ジ に 移 動 で き る よ う に す る に は 、 そ れ ら の HTML ペ ー ジ が あ る 場 所 を 調 べ 、 そ の 場 所 を extdocURL に 指 定 す る 必 要 が あ り ま す 。 こ の オ プ シ ョ ン を 使 う と 、 た と え ば 、 サ ー ド パ ー テ ィ の ド キ ュ メ ン ト か ら 、 http://java.sun.com に あ る java.* の ド キ ュ メ ン ト に リ ン ク す る こ と が で き ま す 。

今 回 の 実 行 で javadoc に よ っ て 生 成 さ れ る ド キ ュ メ ン ト 内 の API だ け を 対 象 に リ ン ク を 作 成 す る 場 合 は 、 −link オ プ シ ョ ン を 省 略 し ま す 。 −link オ プ シ ョ ン が 指 定 さ れ て い な い 場 合 、 javadoc ツ ー ル は 、 外 部 参 照 さ れ た ド キ ュ メ ン ト へ の リ ン ク を 作 成 し ま せ ん 。 こ れ は 、 そ の ド キ ュ メ ン ト が 存 在 す る か ど う か 、 あ る い は 存 在 し て い て も ど こ に 存 在 し て い る の か を 判 別 で き な い か ら で す 。

こ の オ プ シ ョ ン は 、 生 成 ド キ ュ メ ン ト 内 の 複 数 の 場 所 に リ ン ク を 作 成 で き ま す 。

ま た 、 こ の オ プ シ ョ ン を 使 う と 、 複 数 の パ ッ ケ ー ジ 群 の 間 に ク ロ ス リ ン ク を 作 成 す る こ と も で き ま す 。 つ ま り 、 あ る 一 式 の パ ッ ケ ー ジ に 対 し て javadoc を 実 行 し た あ と 、 別 の 一 式 の パ ッ ケ ー ジ に 対 し て javadoc を 実 行 し 、 こ れ ら 2 つ の パ ッ ケ ー ジ 群 の 間 に ク ロ ス リ ン ク を 作 成 で き ま す 。 3 番 目 の 使 い 方 は 、 ド キ ュ メ ン ト を 更 新 す る た め の 「 ハ ッ ク 」 用 で す 。 つ ま り 、 ま ず 、 パ ッ ケ ー ジ 全 体 に javadoc を 実 行 し て 、 次 に 、 変 更 さ れ た パ ッ ケ ー ジ だ け に javadoc を も う 一 度 実 行 し ま す 。 す る と 、 更 新 さ れ た フ ァ イ ル だ け を オ リ ジ ナ ル の パ ッ ケ ー ジ に 挿 入 し 直 す こ と に な り ま す 。

参 照 ク ラ ス の バ グ 修 正 - 1.4 で は 、 次 の バ グ が 修 正 さ れ ま し た 。

1.2 お よ び 1.3 で の リ ン ク に 関 す る バ グ
- @see ま た は {@link} で 除 外 ク ラ ス を 参 照 し 、
−link を 使 用 し た 場 合 、 実 際 に ハ イ パ ー リ ン ク が
作 成 さ れ る の は 、 そ の ク ラ ス が import 文 か 宣 言 の
ど ち ら か で 参 照 さ れ て い る 場 合 に 限 ら れ ま す 。
メ ソ ッ ド の 本 体 で 参 照 さ れ て い る だ け で は 不 十 分 で す 。
対 策 と し て は 、 そ の 参 照 ク ラ ス の import 文 を 明 示 的 に
(ま た は ワ イ ル ド カ ー ド を 使 用 し て ) 追 加 し ま す 。

@see ま た は -link を 使 っ た {@link} 参 照 に よ り 、 参 照 ク ラ ス を 読 み 込 み 、 リ ン ク を 作 成 で き る よ う に な り ま し た 。 以 前 に 回 避 策 と し て 追 加 し た import 文 は 削 除 で き ま す 。 こ の import 文 に は 、 次 の 例 の よ う に コ メ ン ト を 追 加 す る こ と を 推 奨 し て い ま し た 。

import java.lang.SecurityManager; // workaround to force @see/@link\
hyperlink

パ ッ ケ ー ジ リ ス ト : −link オ プ シ ョ ン で は 、 javadoc ツ ー ル に よ っ て 生 成 さ れ た package-list と い う 名 前 の フ ァ イ ル が 、 こ の オ プ シ ョ ン で 指 定 す る URL に 存 在 し て い る 必 要 が あ り ま す 。 package-list フ ァ イ ル は 、 そ の 場 所 で ド キ ュ メ ン ト 化 さ れ て い る パ ッ ケ ー ジ の 名 前 の リ ス ト を 含 む 単 純 な テ キ ス ト フ ァ イ ル で す 。 前 の 例 で は 、 javadoc ツ ー ル は 、 指 定 さ れ た URL に あ る package-list と い う 名 前 の フ ァ イ ル を 探 し 、 パ ッ ケ ー ジ 名 を 読 み 込 ん で 、 そ の URL に あ る そ れ ら の パ ッ ケ ー ジ へ の リ ン ク を 作 成 し ま し た 。

た と え ば 、 Java プ ラ ッ ト フ ォ ー ム v1.4 API の パ ッ ケ ー ジ リ ス ト は 以 下 に あ り 、

http://java.sun.com/products/jdk/1.2/docs/\
api/package-list

次 の よ う な 内 容 で 始 ま っ て い ま す 。

java.applet
java.awt
java.awt.color
java.awt.datatransfer
java.awt.dnd
java.awt.event
java.awt.font
そ の 他 ...

−link オ プ シ ョ ン を 指 定 せ ず に javadoc ツ ー ル を 実 行 し た 場 合 、 ド キ ュ メ ン ト の 生 成 時 に 外 部 参 照 ク ラ ス に 属 す る 名 前 を 見 つ け る と 、 javadoc は そ の 名 前 を リ ン ク を 持 た な い 形 で 出 力 し ま す 。 一 方 、 −link オ プ シ ョ ン が 指 定 さ れ て い る 場 合 、 javadoc ツ ー ル は 、 指 定 さ れ た extdocURL の 場 所 に あ る package-list フ ァ イ ル か ら 、 該 当 す る 名 前 の パ ッ ケ ー ジ を 探 し ま す 。 パ ッ ケ ー ジ 名 が 見 つ か っ た 場 合 は 、 そ の extdocURL を 名 前 の 前 に 付 け ま す 。

す べ て の リ ン ク が 正 し く 機 能 す る た め に は 、 外 部 参 照 の ド キ ュ メ ン ト の す べ て が 、 指 定 さ れ た URL に 存 在 し て い な け れ ば な り ま せ ん 。 javadoc ツ ー ル は 、 package-list が 存 在 す る か ど う か を 調 べ る だ け で 、 指 定 さ れ た URL に 目 的 の ペ ー ジ が 存 在 す る か ど う か は チ ェ ッ ク し ま せ ん 。

複 数 の リ ン ク : 複 数 の −link オ プ シ ョ ン を 提 供 し て 、 外 部 で 生 成 さ れ た ド キ ュ メ ン ト に 任 意 数 の リ ン ク を 設 定 で き ま す 。 Javadoc 1.2 に は 、 複 数 の -link コ マ ン ド を 提 供 で き な い と い う バ グ が あ り ま す 。 こ の バ グ は 、 1.2.2 で 修 正 さ れ ま し た 。

リ ン ク す る 外 部 ド キ ュ メ ン ト ご と に 別 の リ ン ク オ プ シ ョ ン を 指 定 し ま す 。

example% javadoc −link extdocURL1 −link extdocURL2 ... \
−link extdocURLn com.mypackage

extdocURL1、 extdocURL2、 ... extdocURLn は 、 そ れ ぞ れ 外 部 ド キ ュ メ ン ト の ル ー ト を 指 し 、 各 ル ー ト に は 、 package-list と い う 名 前 の フ ァ イ ル が 含 ま れ て い ま す 。

ク ロ ス リ ン ク - ま だ 生 成 さ れ て い な い 2 つ 以 上 の ド キ ュ メ ン ト を ク ロ ス リ ン ク す る 場 合 は 、 「 ブ ー ト ス ト ラ ッ ピ ン グ 」 が 必 要 に な る こ と に 注 意 し て く だ さ い 。 言 い 換 え る と 、 ど の ド キ ュ メ ン ト の package-list も 存 在 し て い な い 場 合 、 最 初 の ド キ ュ メ ン ト に 対 し て javadoc ツ ー ル を 実 行 し た 時 点 で は 、 2 番 目 の ド キ ュ メ ン ト の package-list は ま だ 存 在 し て い ま せ ん 。 し た が っ て 、 外 部 リ ン ク を 作 成 す る に は 、 2 番 目 の ド キ ュ メ ン ト を 生 成 し た あ と 、 最 初 の ド キ ュ メ ン ト を 生 成 し 直 す 必 要 が あ り ま す 。

こ の 場 合 、 最 初 に 行 う ド キ ュ メ ン ト 生 成 の 目 的 は 、 package-list を 作 成 す る こ と で す 。 パ ッ ケ ー ジ 名 を す べ て 把 握 し て い る 場 合 は 、 package-list を 手 動 で 作 成 す る こ と も で き ま す 。 次 に 、 2 番 目 の ド キ ュ メ ン ト と そ の 外 部 リ ン ク を 生 成 し ま す 。 javadoc ツ ー ル は 、 必 要 な 外 部 の package-list フ ァ イ ル が 存 在 し な い 場 合 は 、 警 告 を 表 示 し ま す 。
−linkoffline extdocURL packagelistLoc

こ の オ プ シ ョ ン は 、 −link オ プ シ ョ ン を 変 え た も の で す 。 ど ち ら も 、 javadoc で 生 成 さ れ た 外 部 参 照 ク ラ ス の ド キ ュ メ ン ト へ の リ ン ク を 作 成 し ま す 。 Javadoc ツ ー ル が 「 オ フ ラ イ ン 」 で 、 Web 上 の ド キ ュ メ ン ト に リ ン ク す る 場 合 は 、 Web 接 続 経 由 で は ド キ ュ メ ン ト に ア ク セ ス で き な い た め 、 −linkoffline オ プ シ ョ ン を 使 用 し ま す 。

つ ま り 、 外 部 ド キ ュ メ ン ト の package-list フ ァ イ ル が ア ク セ ス で き な い 、 ま た は extdocURL ロ ケ ー シ ョ ン に 存 在 し な い が 、 packageListLoc で 指 定 で き る 別 の ロ ケ ー シ ョ ン (通 常 は ロ ー カ ル ) に 存 在 し て い る 場 合 に は 、 −linkoffline を 使 用 す る と い う こ と で す 。 し た が っ て 、 extdocURL に WWW 上 で し か ア ク セ ス で き な い 場 合 は 、 −linkoffline を 指 定 す る こ と に よ り 、 ド キ ュ メ ン ト の 生 成 時 に javadoc ツ ー ル が Web に 接 続 で き な け れ ば な ら な い と い う 制 約 が な く な り ま す 。 例 を あ と で 示 し ま す 。

−linkoffline オ プ シ ョ ン に は 2 つ の 引 数 が あ り ま す 。 1 つ は <a href> リ ン ク に 埋 め 込 む 文 字 列 、 も う 1 つ は package-list: の 検 索 場 所 を 示 し ま す 。

javadoc の 1 回 の 実 行 で 、 複 数 の −linkoffline オ プ シ ョ ン を 指 定 で き ま す 。 1.2.2 よ り 前 の バ ー ジ ョ ン で は 、 複 数 の オ プ シ ョ ン は 指 定 で き ま せ ん で し た 。

外 部 ド キ ュ メ ン ト へ の 絶 対 リ ン ク を 使 っ た 例 - java.lang 、 java.io 、 お よ び そ の 他 の Java 2 プ ラ ッ ト フ ォ ー ム パ ッ ケ ー ジ (http://java.sun.com/j2se/1.4/docs/api) に リ ン ク し た く て も 、 Web に ア ク セ ス で き な い 場 合 に つ い て 考 え て み ま す 。 package-list フ ァ イ ル を ブ ラ ウ ザ で 開 き (http://java.sun.com/j2se/1.4/docs/api/package-list)、 ロ ー カ ル デ ィ レ ク ト リ に 保 存 し ま す 。 次 に 、 2 番 目 の 引 数 packagelistLoc で そ の ロ ー カ ル コ ピ ー を 指 定 し ま す 。 こ の と き 、 パ ッ ケ ー ジ リ ス ト フ ァ イ ル は 現 在 の デ ィ レ ク ト リ 「 .」 に 保 存 さ れ て い ま す 。 次 の コ マ ン ド は 、 Java 2 プ ラ ッ ト フ ォ ー ム パ ッ ケ ー ジ へ の リ ン ク を 含 む 、 com.mypackage パ ッ ケ ー ジ の ド キ ュ メ ン ト を 生 成 し ま す 。 生 成 さ れ た ド キ ュ メ ン ト に は 、 た と え ば ク ラ ス ツ リ ー 内 の Object ク ラ ス へ の リ ン ク が 含 ま れ て い ま す (−sourcepath な ど の 他 の 必 要 な オ プ シ ョ ン は 表 示 さ れ ま せ ん )。

% javadoc -linkoffline http://java.sun.com/j2se/1.4/docs/api . com.mypackage

外 部 ド キ ュ メ ン ト へ の 相 対 リ ン ク を 使 っ た 例 - −linkoffline を 相 対 パ ス で 指 定 す る の は あ ま り 一 般 的 で は あ り ま せ ん 。 通 常 は 、 −link で 十 分 だ か ら で す 。 −linkoffline を 使 用 し て い る 場 合 、 package-list フ ァ イ ル は 通 常 ロ ー カ ル で 、 相 対 リ ン ク を 使 用 し て い る 場 合 は 、 リ ン ク 先 の フ ァ イ ル も ロ ー カ ル で あ る の が 普 通 で す 。 そ の た め 、 −linkoffline に 2 つ の 異 な る 引 数 の パ ス を 与 え る 必 要 は あ り ま せ ん 。 2 つ の 引 数 が 同 じ で あ る 場 合 、 −link を 使 用 で き ま す 。 −link の 相 対 リ ン ク の 使 用 例 を 参 照 し て く だ さ い 。

package-list フ ァ イ ル の 手 動 作 成 - package-list フ ァ イ ル が ま だ 存 在 し な く て も 、 ド キ ュ メ ン ト の リ ン ク 先 の パ ッ ケ ー ジ 名 が わ か っ て い る 場 合 は 、 こ の フ ァ イ ル の コ ピ ー を 自 分 で 作 成 し 、 packagelistLoc で そ の パ ス を 指 定 す る こ と が で き ま す 。 com.apipackage が 最 初 に 作 成 さ れ た と き に com.spipackage の パ ッ ケ ー ジ リ ス ト が 存 在 し な か っ た 、 以 前 の 場 合 が そ の 例 で す 。 こ の 方 法 は 、 パ ッ ケ ー ジ 名 は わ か っ て い る も の の 、 ま だ 公 開 さ れ て い な い 、 新 し い 外 部 ド キ ュ メ ン ト に リ ン ク す る ド キ ュ メ ン ト を 生 成 す る 場 合 に 便 利 で す 。 ま た 、 Javadoc 1.0 ま た は 1.1 で は package-list フ ァ イ ル が 生 成 さ れ な い た め 、 こ の 方 法 で 、 こ れ ら の バ ー ジ ョ ン で 生 成 さ れ た パ ッ ケ ー ジ の package-list フ ァ イ ル を 生 成 で き ま す 。 2 つ の 会 社 が 未 公 開 の package-list フ ァ イ ル を 共 有 す る こ と も で き る た め 、 ク ロ ス リ ン ク を 設 定 し た ド キ ュ メ ン ト を 同 時 に リ リ ー ス す る こ と も 可 能 で す 。

複 数 の ド キ ュ メ ン ト に リ ン ク - −linkoffline は 、 参 照 先 の 生 成 ド キ ュ メ ン ト ご と に 1 つ ず つ 指 定 し ま す 。 次 の 例 で は 、 わ か り や す く す る た め に オ プ シ ョ ン ご と に 行 を 分 け て い ま す 。

example% javadoc −linkoffline docURL1 packagelistURL1 \
−linkoffline docURL2 packagelistURL2 \
...

ド キ ュ メ ン ト の 更 新 : −linkoffline オ プ シ ョ ン の も う 1 つ の 用 途 は 、 プ ロ ジ ェ ク ト で 多 数 の パ ッ ケ ー ジ を 使 い 、 す で に ツ リ ー 全 体 に 対 し て javadoc を 実 行 し て あ る 場 合 に 、 次 の 実 行 で は 、 す ば や く 細 か い 変 更 を 行 な っ て か ら 、 ソ ー ス ツ リ ー の 一 部 に 対 し て だ け javadoc を 実 行 し 直 し た い 場 合 に 便 利 で す 。 こ れ は 、 変 更 が ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト に 対 し て で あ り 、 シ グ ニ チ ャ に 対 し て で は な い 場 合 に だ け 正 常 に 処 理 さ れ る の で 、 ハ ッ キ ン グ の よ う な も の で す 。 ソ ー ス コ ー ド に 対 し て シ グ ニ チ ャ を 追 加 、 削 除 ま た は 変 更 し た 場 合 は 、 索 引 、 パ ッ ケ ー ジ ツ リ ー 、 継 承 さ れ る メ ン バ の リ ス ト 、 [使 用 ] ペ ー ジ な ど の 場 所 で 壊 れ た リ ン ク が 表 示 さ れ ま す 。

ま ず 、 新 し い 実 行 の た め 、 新 規 の 生 成 先 デ ィ レ ク ト リ (update) を 作 成 し ま す 。 −linkoffline の 1 番 目 の 引 数 に 現 在 の デ ィ レ ク ト リ 「 .」 を 設 定 し 、 2 番 目 の 引 数 に package-list を 検 索 す る 場 所 で あ る オ リ ジ ナ ル の ド キ ュ メ ン ト へ の 相 対 パ ス (html) を 設 定 し ま す 。

example% javadoc −d update −linkoffline . html com.mypackage

javadoc の 実 行 が 終 了 し た と き 、 update 内 に 生 成 さ れ た フ ァ イ ル (概 要 や 索 引 で は な い ) で 、 html 内 に あ る オ リ ジ ナ ル の フ ァ イ ル を 上 書 き コ ピ ー し ま す 。
−linksource

各 ソ ー ス フ ァ イ ル (行 番 号 付 き ) の HTML バ ー ジ ョ ン を 作 成 し 、 標 準 の HTML ド キ ュ メ ン ト か ら の リ ン ク を 追 加 し ま す 。 こ の オ プ シ ョ ン に よ り 、 含 ま れ る ソ ー ス フ ァ イ ル 内 の す べ て の private 実 装 の 詳 細 が 開 示 さ れ ま す 。 開 示 さ れ る も の に は 、 private ク ラ ス 、 private フ ィ ー ル ド 、 お よ び private メ ソ ッ ド の 本 文 (−public、 −package、 −protected、 −private と い っ た オ プ シ ョ ン に か か わ ら ず ) が 含 ま れ ま す 。 −private オ プ シ ョ ン を 指 定 し て い な い 場 合 は 、 す べ て の private ク ラ ス ま た は イ ン タ フ ェ ー ス が リ ン ク を 介 し て ア ク セ ス で き る わ け で は あ り ま せ ん 。

−group groupheading packagepattern:packagepattern:...

概 要 ペ ー ジ の 複 数 の パ ッ ケ ー ジ を 指 定 の グ ル ー プ に 分 け 、 グ ル ー プ 単 位 で 表 を 作 成 し ま す 。 各 グ ル ー プ は 、 そ れ ぞ れ 別 の −group オ プ シ ョ ン で 指 定 し ま す 。 こ れ ら の グ ル ー プ は 、 コ マ ン ド 行 で 指 定 し た 順 序 で ペ ー ジ に 表 示 さ れ ま す 。 パ ッ ケ ー ジ は 、 1 つ の グ ル ー プ 内 で は ア ル フ ァ ベ ッ ト 順 に 並 べ ら れ ま す 。 各 −group オ プ シ ョ ン で は 、 packagepattern 式 の リ ス ト に 一 致 す る パ ッ ケ ー ジ が 、 見 出 し groupheading を 持 つ 1 つ の 表 に ま と め て 表 示 さ れ ま す 。

注 : パ タ ー ン や パ タ ー ン リ ス ト 内 で ア ス タ リ ス ク を 使 う 場 合 は 、 "java.lang*:java.util" の よ う に 、 パ タ ー ン リ ス ト を 引 用 符 で 囲 む 必 要 が あ り ま す 。

−group オ プ シ ョ ン が 1 つ も 指 定 さ れ て い な い 場 合 は 、 す べ て の パ ッ ケ ー ジ が 、 [パ ッ ケ ー ジ ] と い う 見 出 し を 持 つ 1 つ の グ ル ー プ に 入 れ ら れ ま す 。 ド キ ュ メ ン ト 化 さ れ る パ ッ ケ ー ジ の 中 に 、 指 定 し た グ ル ー プ の ど の グ ル ー プ に も 入 ら な い パ ッ ケ ー ジ が あ る 場 合 、 こ の よ う な パ ッ ケ ー ジ は [そ の 他 の パ ッ ケ ー ジ ] と い う 見 出 し を 持 つ 独 立 し た グ ル ー プ に 入 れ ら れ ま す 。

た と え ば 、 次 の よ う に オ プ シ ョ ン を 指 定 す る と 、 ド キ ュ メ ン ト 化 さ れ る 4 つ の パ ッ ケ ー ジ は 、 コ ア パ ッ ケ ー ジ 、 拡 張 機 能 パ ッ ケ ー ジ 、 お よ び そ の 他 の パ ッ ケ ー ジ に 分 か れ ま す 。 java.lang* で は 、 後 続 の ド ッ ト が な い こ と に 注 意 し て く だ さ い 。 java.lang.* の よ う に ド ッ ト を 入 れ る と 、 java.lang パ ッ ケ ー ジ は 含 ま れ な い こ と に な り ま す 。

example% javadoc −group "Core Packages" "java.lang*:java.util" \
−group "Extension Packages" "javax.*" \
java.lang java.lang.reflect java.util javax.servlet java.new

こ の 結 果 、 次 の よ う な グ ル ー プ 化 が 行 わ れ ま す 。

Core Packages
java.lang
java.lang.reflect
java.util
Extension Packages
javax.servlet
Other Packages
java.new

−nodeprecated

推 奨 さ れ な い API を ド キ ュ メ ン ト に 生 成 す る こ と を 禁 止 し ま す 。 こ れ は 、 −nodeprecatedlist オ プ シ ョ ン を 指 定 し た 場 合 の 動 作 に 加 え て 、 ド キ ュ メ ン ト の ほ か の 部 分 を 通 じ て 、 推 奨 さ れ な い API を 生 成 し な い こ と と 同 じ で す 。 こ の オ プ シ ョ ン は 、 コ ー ド を 記 述 し て い て 、 推 奨 さ れ な い コ ー ド を 無 視 し た い 場 合 に 便 利 で す 。

−nodeprecatedlist

推 奨 さ れ な い API の リ ス ト を 含 む フ ァ イ ル (deprecated-list.html) の 生 成 を 禁 止 し ま す 。 ま た 、 こ の ペ ー ジ へ の リ ン ク を ナ ビ ゲ ー シ ョ ン バ ー に 生 成 す る こ と を 禁 止 し ま す 。 た だ し 、 ド キ ュ メ ン ト の ほ か の 部 分 で は 、 推 奨 さ れ な い API の 生 成 を 続 行 し ま す 。 こ の オ プ シ ョ ン は 、 推 奨 さ れ な い API が ソ ー ス コ ー ド に 含 ま れ て お ら ず 、 ナ ビ ゲ ー シ ョ ン バ ー を す っ き り と 見 せ た い 場 合 に 便 利 で す 。

−nosince

生 成 さ れ る ド キ ュ メ ン ト か ら 、 @since タ グ に 関 連 し た 「 Since」 セ ク シ ョ ン を 削 除 し ま す 。

−notree

生 成 さ れ る ド キ ュ メ ン ト か ら ク ラ ス お よ び イ ン タ フ ェ ー ス 階 層 を 省 略 し ま す 。 デ フ ォ ル ト で は 、 階 層 が 作 成 さ れ ま す 。

−noindex

生 成 さ れ る ド キ ュ メ ン ト か ら 索 引 を 省 略 し ま す 。 デ フ ォ ル ト で は 、 索 引 が 作 成 さ れ ま す 。

−nohelp

各 出 力 ペ ー ジ の 最 上 部 と 最 下 部 の ナ ビ ゲ ー シ ョ ン バ ー か ら [ヘ ル プ ] リ ン ク を 省 略 し ま す 。

−nonavbar

生 成 さ れ る ペ ー ジ の 最 上 部 と 最 下 部 に 表 示 さ れ る ナ ビ ゲ ー シ ョ ン バ ー 、 ヘ ッ ダ 、 お よ び フ ッ タ の 生 成 を 禁 止 し ま す 。 こ の オ プ シ ョ ン は 、 bottom オ プ シ ョ ン に は 影 響 し ま せ ん 。 −nonavbar オ プ シ ョ ン は 、 印 刷 す る た め だ け に フ ァ イ ル を PostScript ま た は PDF に 変 換 す る 場 合 な ど 、 内 容 だ け が 重 要 で ナ ビ ゲ ー シ ョ ン の 必 要 性 が な い 場 合 に 便 利 で す 。

−helpfile path/filename

上 部 と 下 部 の ナ ビ ゲ ー シ ョ ン バ ー の [ヘ ル プ ] リ ン ク の リ ン ク 先 と な る 代 替 ヘ ル プ フ ァ イ ル path/filename の パ ス を 指 定 し ま す 。 こ の オ プ シ ョ ン が 指 定 さ れ て い な い 場 合 、 javadoc は 、 javadoc に ハ ー ド コ ー ド さ れ て い る ヘ ル プ フ ァ イ ル help-doc.html を 自 動 的 に 作 成 し ま す 。 こ の オ プ シ ョ ン を 使 え ば 、 デ フ ォ ル ト の 設 定 を オ ー バ ー ラ イ ド で き ま す 。 フ ァ イ ル 名 に は ど の よ う な 名 前 も 指 定 で き 、 help-doc.html に は 限 定 さ れ ま せ ん 。 javadoc は 、 そ れ に 従 っ て 、 ナ ビ ゲ ー シ ョ ン バ ー に あ る リ ン ク に 調 整 を 加 え ま す 。 次 に 例 を 示 し ま す 。

example% javadoc −helpfile /home/doc/myhelp.html java.awt

−stylesheetfile path/filename

代 替 HTML ス タ イ ル シ ー ト フ ァ イ ル の パ ス を 指 定 し ま す 。 こ の オ プ シ ョ ン が 指 定 さ れ て い な い 場 合 、 javadoc ツ ー ル は 、 内 部 的 に ハ ー ド コ ー ド さ れ て い る ス タ イ ル シ ー ト フ ァ イ ル stylesheet.css を 自 動 的 に 作 成 し ま す 。 こ の オ プ シ ョ ン を 使 え ば 、 デ フ ォ ル ト の 設 定 を オ ー バ ー ラ イ ド で き ま す 。 filename に は ど ん な フ ァ イ ル 名 で も 指 定 で き 、 stylesheet.css に は 限 定 さ れ ま せ ん 。 次 に 例 を 示 し ま す 。

example% javadoc −helpfile /home/doc/myhelp.html java.awt

−serialwarn

@serial タ グ が な い 場 合 、 コ ン パ イ ル 時 に 警 告 を 生 成 し ま す 。 デ フ ォ ル ト で は 、 javadoc 1.2.2 (お よ び そ れ 以 降 ) は @serial の 警 告 を 生 成 し ま せ ん 。 (こ れ は 、 以 前 の バ ー ジ ョ ン と は 逆 で す 。 ) @serial の 警 告 を 生 成 す る に は 、 こ の オ プ シ ョ ン を 使 用 し て く だ さ い 。 こ の オ プ シ ョ ン は 、 デ フ ォ ル ト の 直 列 化 可 能 な フ ィ ー ル ド と writeExternal メ ソ ッ ド を 正 し く ド キ ュ メ ン ト 化 す る の に 役 立 ち ま す 。

−charset name

こ の ド キ ュ メ ン ト 用 の HTML 文 字 セ ッ ト を 指 定 し ま す 。 た と え ば 次 の 指 定 は 、

% javadoc −charset "iso-8859-1" mypackage

次 の 行 を 、 生 成 さ れ る 各 ペ ー ジ の 先 頭 に 挿 入 し ま す 。

<META http-equiv="Content-Type" content="text/html; charset=iso-885 9-1">

こ の META タ グ に つ い て は 、 HTML 標 準 (4197265 と 4137321) で 説 明 さ れ て い ま す 。

−docencoding name

出 力 さ れ る HTML フ ァ イ ル の エ ン コ ー デ ィ ン グ を 指 定 し ま す 。

−source1.4

Javadoc で J2SE v 1.4 の ソ ー ス コ ー ド に 存 在 す る ア サ ー シ ョ ン を 処 理 で き る よ う に す る た め に 必 要 で す 。 こ の オ プ シ ョ ン は 、 javac −source 1.4 を 使 用 し て コ ン パ イ ル す る コ ー ド を ド キ ュ メ ン ト 化 し ま す 。

−tag tagname:Xaoptcmf:

1 つ の 引 数 を も つ 簡 単 な カ ス タ ム ス タ ン ド ア ロ ン タ グ で あ る 、 ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト 内 の @tagname を javadoc で 解 釈 で き る よ う に し ま す 。 し た が っ て 、 Javadoc ツ ー ル は タ グ 名 を ス ペ ル チ ェ ッ ク で き ま す 。 ソ ー ス コ ー ド に 存 在 す る す べ て の カ ス タ ム タ グ に −tag オ プ シ ョ ン を 付 け 、 現 在 の 実 行 で 出 力 さ れ て い な い も の を 無 効 化 (Xを 使 用 ) し て お く こ と が 重 要 で す 。

−tag オ プ シ ョ ン は タ グ の 見 出 し で あ る taghead を 太 字 で 出 力 し 、 そ の あ と に 1 つ の 引 数 か ら の テ キ ス ト を 出 力 し ま す 。 そ の 例 は こ の あ と で 表 示 し ま す 。 他 の ス タ ン ド ア ロ ン タ グ と 同 様 に 、 こ の 引 数 の テ キ ス ト に イ ン ラ イ ン タ グ を 含 め 、 解 釈 さ せ る こ と が で き ま す 。 出 力 結 果 は 、 @return や @author と い っ た 標 準 の 1 つ の 引 数 を も つ タ グ と 似 て い ま す 。

タ グ の 配 置 - 引 数 の Xaoptcmf 部 分 は 、 ソ ー ス コ ー ド の ど こ に タ グ の 配 置 が 許 可 さ れ て い る か 、 ま た タ グ を 無 効 に (X を 使 用 ) で き る か ど う か を 判 断 し ま す 。 タ グ の 配 置 を 全 体 に 許 可 す る 場 合 は a、 そ れ 以 外 の 場 合 に つ い て は 、 そ の 他 の 文 字 を 組 み 合 わ せ て 指 定 で き ま す 。

X (タ グ の 無 効 化 )
a (全 部 )
o (概 要 )
p (パ ッ ケ ー ジ )
t (タ イ プ 、 つ ま り ク ラ ス お よ び イ ン タ フ ェ ー ス )
c (コ ン ス ト ラ ク タ )
m (メ ソ ッ ド )
f (フ ィ ー ル ド )

シ ン グ ル タ グ の 例 - ソ ー ス コ ー ド の 任 意 の 場 所 で 使 用 で き る タ グ の タ グ オ プ シ ョ ン の 例 を 示 し ま す 。

−tag todo:a:"To Do:"

コ ン ス ト ラ ク タ 、 メ ソ ッ ド 、 お よ び フ ィ ー ル ド だ け で @todo を 使 用 さ せ る に は 、 次 の よ う に し ま す 。

−tag todo:cmf:"To Do:"

上 記 で は 、 末 尾 の コ ロ ン (:) が パ ラ メ ー タ の 区 切 り 記 号 で は な く 、 表 示 の と お り 、 見 出 し テ キ ス ト の 一 部 で あ る こ と に 注 意 し て く だ さ い 。 次 の よ う に 、 @todo タ グ を 含 む ソ ー ス コ ー ド に ど ち ら か の タ グ オ プ シ ョ ン を 使 用 し ま す 。

@todo The documentation for this method needs work.

こ の 行 は 次 の よ う に 出 力 さ れ ま す 。

To Do:

タ グ 名 の ス ペ ル チ ェ ッ ク (タ グ の 無 効 化 ) -
開 発 者 は 、 ソ ー ス コ ー ド の 中 で 出 力 で き な い カ ス タ ム タ グ を
使 用 す る こ と が あ り ま す 。 そ の 場 合 、 ソ ー ス タ グ に 存 在 す る
す べ て の タ グ を リ ス ト し 、 出 力 す る タ グ を 有 効 化 し 、
出 力 し な い タ グ を 無 効 化 す る こ と が 重 要 で す 。
X を 使 用 す る と タ グ を 無 効 化 で き 、 こ れ が な い 場 合 は
タ グ が 有 効 と な り ま す 。 こ の 文 字 の 存 在 に よ っ て 、
Javadoc
ツ ー ル は 、 検 出 し た タ グ が 未 知 の タ グ で 、
お そ ら く 綴 り 間 違 い で あ る と 判 断 で き ま す 。
こ の 場 合 、 警 告 メ ッ セ ー ジ が 表 示 さ れ ま す 。

す で に 存 在 す る 、 配 置 を 指 定 す る 引 数 の 値 に X を 追 加 し た 場 合 、
タ グ を 有 効 に し た い と き に X を 削 除 で き ま す 。
た と え ば 、 @todo が 出 力 し な い タ グ の 場 合 、 次 の よ う に し ま す 。

−tag todo:Xcmf:"To Do:"

ま た は 、 次 の よ う に よ り 簡 単 に す る こ と も で き ま す 。

−tag todo:X

−tag todo:X の 構 文 は 、 @todo が タ グ レ ッ ト で 定 義 さ れ て い る 場 合 も 有 効 で す 。

タ グ の 順 序 - −tag (お よ び −taglet) オ プ シ ョ ン の 順 序 に 従 っ て タ グ が 出 力 さ れ ま す 。 カ ス タ ム タ グ と 標 準 タ グ を 混 在 さ せ る こ と が で き ま す 。 標 準 タ グ の タ グ オ プ シ ョ ン は 、 順 序 を 決 定 す る た め だ け の プ レ ー ス ホ ル ダ で す 。 こ れ ら は 標 準 タ グ 名 だ け を 使 用 し ま す (標 準 タ グ の 小 見 出 し は 変 更 で き ま せ ん )。 こ れ を 次 の 例 に 示 し ま す 。

−tag が な い 場 合 、 −taglet の 場 所 に よ っ て そ の 順 序 が 決 ま り ま す 。 こ の 2 つ が 両 方 あ る 場 合 は 、 コ マ ン ド 行 の 最 後 に 使 用 さ れ た 方 が 順 序 を 決 定 し ま す (こ れ は 、 タ グ と タ グ レ ッ ト が 、 コ マ ン ド 行 で 使 用 さ れ た 順 に 処 理 さ れ る た め で す )。 た と え ば 、 −taglet と −tag が 両 方 と も todo と い う 名 前 で あ る 場 合 、 コ マ ン ド 行 の 最 後 で 使 用 さ れ た 方 が 順 序 を 決 定 し ま す 。

タ グ の 完 全 な セ ッ ト の 例 - こ の 例 で は 、 出 力 の Parameters と Throws の 間 に ToDo を 挿 入 し ま す 。 「 X」 を 使 用 し て 、 @example が ソ ー ス コ ー ド 内 の 今 回 の 実 行 で 出 力 さ れ な い タ グ で あ る こ と を 指 定 で き ま す 。 @argfile を 使 用 す る と 、 次 の よ う に 行 の 継 続 文 字 な し で 、 引 数 フ ァ イ ル の 異 な る 行 に タ グ を 配 置 で き ま す 。

−tag param
−tag return
−tag todo:a:"To Do:"
−tag throws
−tag see
−tag example:X

javadoc が ド キ ュ メ ン テ ー シ ョ ン コ メ ン ト を 解 析 す る 際 に 、 検 出 さ れ た タ グ の う ち 、 標 準 タ グ で も な く 、 −tag や −taglet で 渡 さ れ る タ グ で も な い も の は 、 不 明 な タ グ と し て 認 識 し 、 警 告 が ス ロ ー さ れ ま す 。

標 準 タ グ は 、 最 初 、 デ フ ォ ル ト の 順 序 で リ ス ト 内 部 的 に 格 納 さ れ ま す 。 −tag オ プ シ ョ ン を 使 用 す る と 、 こ の タ グ が リ ス ト に 追 加 さ れ ま す 。 標 準 タ グ は デ フ ォ ル ト の 位 置 か ら 移 動 し ま す 。 そ の た め 、 標 準 タ グ で −tag オ プ シ ョ ン が 省 略 さ れ る と 、 デ フ ォ ル ト の 位 置 に 配 置 さ れ た ま ま に な り ま す 。

競 合 の 回 避 - 固 有 の ネ ー ム ス ペ ー ス を 細 か く 分 け る に は 、 パ ッ ケ ー ジ に 使 用 さ れ て い る com.mycompany.todo と い う 名 前 の よ う に 、 ド ッ ト (.) を 区 切 り 記 号 と す る 名 前 を 使 い ま す 。 Sun は 今 後 も ド ッ ト を 含 ま な い 標 準 タ グ を 作 成 し ま す 。 ユ ー ザ が 作 成 し た タ グ は 、 Sun が 定 義 し た 同 じ 名 前 の タ グ の 動 作 を オ ー バ ー ラ イ ド し ま す 。 つ ま り 、 ユ ー ザ が @todo と い う 名 前 の タ グ ま た は タ グ レ ッ ト を 作 成 し て い た 場 合 、 そ の あ と で Sun が 同 じ 名 前 の 標 準 タ グ を 作 成 し て も 、 ユ ー ザ が 定 義 し た 動 作 は そ の ま ま 維 持 さ れ ま す 。

−taglet オ プ シ ョ ン を 使 用 し て 、 よ り 複 雑 な ス タ ン ド ア ロ ン タ グ や カ ス タ ム イ ン ラ イ ン タ グ を 作 成 す る こ と が で き ま す 。
−taglet " class"

タ グ の ド キ ュ メ ン ト の 生 成 に 使 う タ グ レ ッ ト を 起 動 す る た め の ク ラ ス フ ァ イ ル を 指 定 し ま す 。 ク ラ ス の 完 全 修 飾 名 を 指 定 し て く だ さ い 。 こ の タ グ レ ッ ト は 、 カ ス タ ム タ グ が 持 っ て い る テ キ ス ト 引 数 の 数 も 定 義 し ま す 。 タ グ レ ッ ト は こ れ ら の 引 数 を 受 け 取 り 、 処 理 し 、 出 力 を 生 成 し ま す 。 タ グ レ ッ ト の 例 の 詳 細 に つ い て は 、 タ グ レ ッ ト の 概 要 を 参 照 し て く だ さ い 。

タ グ レ ッ ト は ス タ ン ド ア ロ ン タ グ ま た は イ ン ラ イ ン タ グ に 使 用 す る と 便 利 で す 。 タ グ レ ッ ト で は 任 意 の 数 の 引 数 を 持 つ こ と が で き 、 カ ス タ ム の 動 作 を 実 装 で き ま す 。 た と え ば 、 テ キ ス ト を 太 字 に し た り 、 箇 条 書 き 形 式 に し た り 、 テ キ ス ト を フ ァ イ ル に 書 き 出 し た り 、 他 の プ ロ セ ス を 起 動 し た り す る こ と が で き る の で す 。

タ グ レ ッ ト へ の パ ス を 指 定 す る に は 、 −tagletpath オ プ シ ョ ン を 使 用 し ま す 。 生 成 さ れ た ペ ー ジ の Parameters と Throws の 間 に To Do タ グ レ ッ ト を 挿 入 す る 例 を 示 し ま す 。

−taglet com.sun.tools.doclets.ToDoTaglet
−tagletpath /home/taglets
−tag return
−tag param
−tag todo
−tag throws
−tag see

−taglet オ プ シ ョ ン を −tag オ プ シ ョ ン の 代 わ り に 使 用 す る こ と も で き ま す が 、 そ の 結 果 、 読 み に く く な り ま す 。
−tagletpath " tagletpathlist"

taglet ク ラ ス フ ァ イ ル (.class) を 探 す た め の 検 索 パ ス を 指 定 し ま す 。 tagletpathlist に は 、 コ ロ ン (:) で 区 切 っ て 複 数 の パ ス を 含 め る こ と が で き ま す 。 Javadoc ツ ー ル は 、 指 定 さ れ た パ ス 以 下 の す べ て の サ ブ デ ィ レ ク ト リ を 検 索 し ま す 。

−subpackages " package1:package2:..."

指 定 さ れ た パ ッ ケ ー ジ 内 の ソ ー ス フ ァ イ ル か ら ド キ ュ メ ン ト を 生 成 し 、 再 帰 的 に サ ブ パ ッ ケ ー ジ を 処 理 し ま す 。 こ の オ プ シ ョ ン は 、 ソ ー ス コ ー ド に 新 し い サ ブ パ ッ ケ ー ジ を 追 加 す る の を 自 動 化 す る の に 便 利 で す 。 各 パ ッ ケ ー ジ は ト ッ プ レ ベ ル の パ ッ ケ ー ジ (java) ま た は 完 全 修 飾 さ れ た サ ブ パ ッ ケ ー ジ (javax.swing) で あ り 、 ソ ー ス フ ァ イ ル を 含 む 必 要 は あ り ま せ ん 。 ワ イ ル ド カ ー ド は 不 要 で 、 か つ 許 可 さ れ て い ま せ ん 。 パ ッ ケ ー ジ の 検 索 場 所 を 指 定 す る に は 、 −sourcepath を 使 用 し ま す 。 例 を 示 し ま す 。

% javadoc −d docs −sourcepath /home/user/src \

こ の コ マ ン ド に よ り 、 java お よ び javax.swing と い う 名 前 の パ ッ ケ ー ジ と 、 そ の す べ て の サ ブ パ ッ ケ ー ジ の ド キ ュ メ ン ト を 生 成 し ま す 。

ま た 、 サ ブ パ ッ ケ ー ジ を 処 理 す る と き 、 サ ブ パ ッ ケ ー ジ を 除 外 す る た め の オ プ シ ョ ン も あ り ま す 。
−exclude " packagename1:packagename2:..."

−subpackages で 作 成 さ れ た リ ス ト か ら 、 指 定 さ れ た パ ッ ケ ー ジ と そ の サ ブ パ ッ ケ ー ジ を 無 条 件 で 除 外 し ま す 。 そ れ ら の パ ッ ケ ー ジ が 前 後 の −subpackages オ プ シ ョ ン に 含 ま れ て い る 場 合 で も 、 除 外 処 理 を 行 い ま す 。 例 を 示 し ま す 。

% javadoc −sourcepath /home/user/src −sourcepath java\

こ れ は java.io 、 java.util 、 java.math を 含 み ま す が 、 java.net お よ び java.lang に ル ー ト を も つ パ ッ ケ ー ジ を 除 外 し ま す 。 こ れ に よ っ て java.lang.ref ( java.lang の サ ブ パ ッ ケ ー ジ ) が 除 外 さ れ る こ と に 注 意 し て く だ さ い 。
−breakiterator

文 の ブ レ ー ク 反 復 子 を 使 っ て 、 最 初 の 文 の 終 わ り を 判 断 で き ま す 。 次 の メ ジ ャ ー リ リ ー ス で は 、 最 初 の 文 の 終 点 を 判 断 す る ア ル ゴ リ ズ ム を 変 更 す る 予 定 で す 。 −breakiterator オ プ シ ョ ン は こ の 新 し い ア ル ゴ リ ズ ム を 使 用 し ま す 。 次 回 の メ ジ ャ ー リ リ ー ス へ の 移 行 が ス ム ー ズ に 行 え る よ う 、 バ ー ジ ョ ン 1.4 の 実 行 時 に は 常 に こ の オ プ シ ョ ン を 使 用 す る こ と を お 勧 め し ま す 。

1.2 お よ び 1.3 で は 、 java.text.BreakIterator ク ラ ス を 使 用 し て 英 語 以 外 の 全 言 語 の 文 の 終 点 を 判 別 し て い ま し た 。 そ の た め 、 −breakiterator オ プ シ ョ ン は 英 文 で の み 有 効 で す 。 英 文 に は ピ リ オ ド の あ と に 空 白 文 字 が 来 る と い う 固 有 の ア ル ゴ リ ズ ム が あ り ま す 。 −breakiterator を 使 用 し な い と 、 最 初 の 文 の 終 点 は 1.2 お よ び 1.3 か ら 変 更 さ れ ず 、 差 異 が あ る 場 所 を 表 示 す る 警 告 が 表 示 さ れ ま す 。

ア ル ゴ リ ズ ム の 違 い に よ り 、 英 語 で は 次 の よ う に な り ま す 。

−docfilessubdirs

doc-files デ ィ レ ク ト リ を 、 下 の 階 層 を 含 め て コ ピ ー で き る よ う に し ま す 。 つ ま り 、 サ ブ デ ィ レ ク ト リ と す べ て の コ ン テ ン ツ が 、 生 成 先 デ ィ レ ク ト リ に 再 帰 的 に コ ピ ー さ れ ま す 。 た と え ば 、 doc-files/example/images デ ィ レ ク ト リ と そ の 中 の フ ァ イ ル が コ ピ ー さ れ ま す 。 サ ブ デ ィ レ ク ト リ を 除 外 す る た め の オ プ シ ョ ン も あ り ま す 。

−excludedocfilessubdirs " name1:name2:..."

doc-files の サ ブ デ ィ レ ク ト リ で 、 指 定 さ れ た 名 前 の も の を 除 外 し ま す 。 こ の オ プ シ ョ ン を 使 用 す る と 、 SCCS お よ び そ の 他 の ソ ー ス コ ー ド 管 理 の サ ブ デ ィ レ ク ト リ を コ ピ ー し な い よ う に で き ま す 。

−noqualifier " all |
packagename1:packagename2:..."

修 飾 パ ッ ケ ー ジ 名 を 、 出 力 の ク ラ ス 名 の 前 か ら 削 除 し ま す 。 −noqualifier の 引 数 は all (す べ て の パ ッ ケ ー ジ 修 飾 子 を 削 除 )、 ま た は コ ロ ン で 区 切 ら れ た パ ッ ケ ー ジ リ ス ト の い ず れ か で 、 修 飾 子 と し て 削 除 さ れ ま す 。 ワ イ ル ド カ ー ド も 使 用 で き ま す 。 パ ッ ケ ー ジ 名 は ク ラ ス 名 ま た は イ ン タ フ ェ ー ス 名 が 表 示 さ れ た と こ ろ か ら 削 除 さ れ ま す 。

次 の 例 で は 、 す べ て の パ ッ ケ ー ジ 修 飾 子 を 省 略 し ま す 。

−noqualifier all

次 の 例 で は 、 パ ッ ケ ー ジ 修 飾 子 java.lang お よ び java.io を 省 略 し ま す 。

−noqualifier java.lang:java.io

次 の 例 で は 、 java お よ び com.sun か ら 始 ま る (javax を 除 く ) サ ブ パ ッ ケ ー ジ の パ ッ ケ ー ジ 修 飾 子 を 削 除 し ま す 。

−noqualifier java.*:com.sun.*

パ ッ ケ ー ジ 修 飾 子 が 上 記 の 動 作 に 従 っ て 表 示 さ れ る 場 合 、 1.3 で の 次 の 動 作 も 有 効 で あ り 、 さ ら に 修 飾 子 を 削 除 し ま す 。 p.C ク ラ ス の ペ ー ジ で は 、 p パ ッ ケ ー ジ に 所 属 す る ク ラ ス の パ ッ ケ ー ジ 修 飾 子 を 削 除 し ま す 。 こ の 規 則 は 、 −noqualifier が 使 用 さ れ て い る か ど う か に か か わ ら ず 存 在 し ま す 。
−nocomment

記 述 お よ び す べ て の タ グ を 含 む コ メ ン ト 本 文 全 体 を 抑 制 し 、 宣 言 だ け を 生 成 し ま す 。 こ の オ プ シ ョ ン に よ り 、 元 は 異 な る 目 的 の た め だ っ た ソ ー ス フ ァ イ ル を 再 利 用 し 、 新 し い プ ロ ジ ェ ク ト の た め の ス ケ ル ト ン を 作 成 で き る よ う に な り ま し た 。

コ マ ン ド 行 引 数 フ ァ イ ル
javadoc の コ マ ン ド 行 を 短 く し た り 簡 潔 に し た り す る た め に 、 javadoc コ マ ン ド に 対 す る 引 数 (−J オ プ シ ョ ン を 除 く ) が 入 っ た 1 つ 以 上 の フ ァ イ ル を 指 定 す る こ と が で き ま す 。 こ の こ と を 利 用 す れ ば 、 ど の オ ペ レ ー テ ィ ン グ シ ス テ ム 上 で も 、 任 意 の 長 さ の javadoc コ マ ン ド を 作 成 で き ま す 。

引 数 フ ァ イ ル に は 、 Javadoc オ プ シ ョ ン 、 ソ ー ス フ ァ イ ル 名 、 お よ び パ ッ ケ ー ジ 名 を 自 由 に 組 み 合 わ せ て 記 述 で き ま す 。 ま た 、 Javadoc オ プ シ ョ ン に 対 す る 引 数 だ け を 記 述 し て も か ま い ま せ ん 。 フ ァ イ ル 内 の 各 引 数 は 、 空 白 文 字 ま た は 改 行 で 区 切 り ま す 。 引 数 フ ァ イ ル 内 の フ ァ イ ル 名 は 、 現 在 の デ ィ レ ク ト リ か ら 見 た 相 対 パ ス に な り ま す 。 引 数 フ ァ イ ル の 位 置 か ら 見 た 相 対 パ ス で は あ り ま せ ん 。 引 数 フ ァ イ ル 内 の フ ァ イ ル 名 リ ス ト で は 、 ワ イ ル ド カ ー ド (*) は 使 用 で き ま せ ん 。 た と え ば 、 *.java と は 指 定 で き ま せ ん 。 引 数 フ ァ イ ル 内 の 引 数 で @ 文 字 を 使 用 し て 、 複 数 の フ ァ イ ル を 再 帰 的 に 解 釈 す る こ と は サ ポ ー ト さ れ て い ま せ ん 。 ま た 、 −J オ プ シ ョ ン も サ ポ ー ト さ れ て い ま せ ん 。 こ の オ プ シ ョ ン は 起 動 ツ ー ル に 渡 さ れ ま す が 、 起 動 ツ ー ル で は 引 数 フ ァ イ ル を サ ポ ー ト し て い な い か ら で す 。

javadoc を 実 行 す る と き に 、 各 引 数 フ ァ イ ル の パ ス と フ ァ イ ル 名 の 先 頭 に @ 文 字 を 付 け て 渡 し ま す 。 javadoc は 、 @ 文 字 で 始 ま る 引 数 を 見 つ け る と 、 そ の フ ァ イ ル の 内 容 を 展 開 し て 引 数 リ ス ト に 挿 入 し ま す 。

引 数 フ ァ イ ル を 1 つ 指 定 す る 例

argfile と い う 名 前 の 引 数 フ ァ イ ル に す べ て の Javadoc 引 数 を 格 納 し 、 次 の よ う に 使 用 す る こ と が で き ま す 。

% javadoc @argfile

こ の 引 数 フ ァ イ ル に は 、 次 の 例 で 示 さ れ て い る 2 つ の フ ァ イ ル の 内 容 を 両 方 と も 入 れ る こ と が で き ま す 。

引 数 フ ァ イ ル を 2 つ 指 定 す る 例

Javadoc オ プ シ ョ ン 用 に 1 つ 、 パ ッ ケ ー ジ 名 ま た は ソ ー ス フ ァ イ ル 名 用 に 1 つ と い う よ う に 、 2 つ の 引 数 フ ァ イ ル を 作 成 し 、 次 の よ う に し て 使 用 す る こ と が で き ま す 。 な お 、 こ の あ と の リ ス ト で は 、 行 の 継 続 文 字 を 使 用 し て い ま せ ん 。

以 下 の 内 容 を 含 む options と い う 名 前 の フ ァ イ ル を 作 成 し ま す 。

−d docs-filelist
−use
−splitindex
−windowtitle ’Java 2 Platform v1.3 API Specification’
−doctitle ’Java^{<font size="-2">TM</font>} 2\

−header ’<b>Java 2 Platform </b><br><font size="-1">v1.4</font>’
−bottom ’Copyright 1993-2000 Sun Microsystems, Inc. All Rights Reserved.’
−group "Core Packages" "java.*"
−overview /java/pubs/ws/1.3/src/share/classes/overview-core.html
−sourcepath /java/pubs/ws/1.3/src/share/classes

以 下 の 内 容 を 含 む packages と い う 名 前 の フ ァ イ ル を 作 成 し ま す 。

com.mypackage1
com.mypackage2
com.mypackage3

そ の あ と 、 次 の コ マ ン ド を 使 用 し て javadoc を 実 行 し ま す 。

% javadoc @options @packages

パ ス 付 き の 引 数 フ ァ イ ル の 例

引 数 フ ァ イ ル に は 、 パ ス を 指 定 で き ま す 。 た だ し 、 そ の フ ァ イ ル 内 に 指 定 さ れ た フ ァ イ ル 名 は 、 現 在 の 作 業 デ ィ レ ク ト リ か ら 見 た 相 対 パ ス に な り ま す 。 つ ま り 、 下 の 例 の 場 合 は 、 path1 や path2 か ら 見 た 相 対 パ ス で は あ り ま せ ん 。

% javadoc @path1/options @path2/packages

オ プ シ ョ ン の 引 数 の 例

次 に 、 javadoc オ プ シ ョ ン に 対 す る 引 数 だ け を 引 数 フ ァ イ ル に 格 納 す る 例 を 示 し ま す 。 こ こ で は 、 −bottom オ プ シ ョ ン を 例 に 取 り 上 げ ま す 。 そ の オ プ シ ョ ン に は 、 か な り 長 い 引 数 を 指 定 す る こ と が あ る か ら で す 。 ま ず 、 こ の オ プ シ ョ ン の テ キ ス ト 引 数 に な る 次 の よ う な 内 容 を 含 む 、 bottom と い う 名 前 の フ ァ イ ル を 作 成 し ま す 。

Submit a bug or feature</a><br><br>Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. All Rights Reserved.</font>’

そ の あ と 、 次 の よ う に し て javadoc ツ ー ル を 実 行 し ま す 。

% javadoc −bottom @bottom @packages

ま た 、 引 数 フ ァ イ ル の 先 頭 に −bottom オ プ シ ョ ン を 組 み 込 ん で お け ば 、 次 の よ う に し て 実 行 で き ま す 。

% javadoc @bottom @packages

RUNNING

Javadoc の 実 行
バ ー ジ ョ ン 番 号 -

javadoc の バ ー ジ ョ ン 番 号 は javadoc−J−version を 使 用 す る こ と で 確 認 で き ま す 。 標 準 ド ッ ク レ ッ ト の バ ー ジ ョ ン 番 号 は 出 力 ス ト リ ー ム に 表 示 さ れ ま す 。 こ れ は −quiet オ プ シ ョ ン で オ フ に で き ま す 。

プ ロ グ ラ ム か ら 利 用 で き る public イ ン タ フ ェ ー ス -

Java 言 語 で 書 か れ た プ ロ グ ラ ム 内 か ら javadoc ツ ー ル を 呼 び 出 し ま す 。 こ の イ ン タ フ ェ ー ス は om.sun.tools.javadoc.Main (javadoc は 再 入 ) に あ り ま す 。 詳 細 は 、 「 標 準 ド ッ ク レ ッ ト 」 を 参 照 し て く だ さ い 。

使 用 例

javadoc は 、 パ ッ ケ ー ジ 全 体 に 対 し て 実 行 す る こ と も 、 個 々 の ソ ー ス フ ァ イ ル に 対 し て 実 行 す る こ と も で き ま す 。 各 パ ッ ケ ー ジ 名 は 、 そ れ ぞ れ の パ ッ ケ ー ジ 名 に 対 応 す る デ ィ レ ク ト リ 名 を 持 ち ま す 。 次 の 例 で は 、 ソ ー ス フ ァ イ ル は /home/src/java/awt/*java に あ り ま す 。 生 成 先 デ ィ レ ク ト リ は /home/html で す 。

1 つ 以 上 の パ ッ ケ ー ジ の ド キ ュ メ ン ト 化
パ ッ ケ ー ジ を ド キ ュ メ ン ト 化 す る に は 、 そ の パ ッ ケ ー ジ の ソ ー ス フ ァ イ ル (*.java) が 、 パ ッ ケ ー ジ と 同 じ 名 前 を 持 つ デ ィ レ ク ト リ 内 に 存 在 し て い な け れ ば な り ま せ ん 。 パ ッ ケ ー ジ 名 が 複 数 の 識 別 子 で 構 成 さ れ て い る (java.awt.color の よ う に 、 各 識 別 子 は ド ッ ト で 区 切 ら れ て い る ) 場 合 は 、 後 続 の 各 識 別 子 が 下 位 の サ ブ デ ィ レ ク ト リ に 対 応 し て い な け れ ば な り ま せ ん (java/awt/color な ど )。 1 つ の パ ッ ケ ー ジ の た め の 複 数 の ソ ー ス フ ァ イ ル を 、 異 な る 場 所 に あ る 2 つ の デ ィ レ ク ト リ ツ リ ー に 分 け て 格 納 す る こ と も 可 能 で す
( src1/java/awt/color と src2/java/awt/color な ど )。 た だ し 、 そ の 場 合 は 、 −sourcepath に よ っ て 、 そ の 両 方 の 場 所 を 指 定 し な け れ ば な り ま せ ん 。

javadoc を 実 行 す る に は 、 cd コ マ ン ド を 使 っ て デ ィ レ ク ト リ を 変 更 す る か 、 ま た は −sourcepath オ プ シ ョ ン を 使 用 し ま す 。 そ れ ぞ れ の 例 を 次 に 示 し ま す 。

% javadoc −d /home/html −sourcepath /home/src\

他 の パ ッ ケ ー ジ ツ リ ー を 処 理 す る に は 、 java:javax:org.xml.sax の よ う に 、 そ の 名 前 を −subpackages 引 数 に 追 加 し ま す 。

example% cd /home/src/
example% javadoc −d /home/html java.awt java.awt.event

% javadoc -d /home/html -sourcepath /home/src java.awt java.awt.event

% javadoc −d /home/html −sourcepath\
/home/src1:/home/src2 java.awt java.awt.event

結 果 : ど ち ら の ケ ー ス で も 、 パ ッ ケ ー ジ java.awt と java.awt.event の public お よ び protected な ク ラ ス と イ ン タ フ ェ ー ス を 対 象 に 、 HTML 形 式 の ド キ ュ メ ン ト が 生 成 さ れ 、 指 定 さ れ た 生 成 先 デ ィ レ ク ト リ (/home/html) に HTML フ ァ イ ル が 保 存 さ れ ま す 。 2 つ 以 上 の パ ッ ケ ー ジ が 生 成 さ れ る の で 、 ド キ ュ メ ン ト は 、 パ ッ ケ ー ジ の リ ス ト 、 ク ラ ス の リ ス ト 、 お よ び メ イ ン ペ ー ジ の 3 つ の フ レ ー ム を 持 つ こ と に な り ま す 。

1 つ 以 上 の ク ラ ス の ド キ ュ メ ン ト 化
javadoc ツ ー ル を 実 行 す る 2 番 目 の 方 法 は 、 1 つ 以 上 の ソ ー ス フ ァ イ ル ( .java ) を 渡 す こ と で す 。 javadoc は 、 次 の 2 つ の ど ち ら か の 方 法 で 実 行 で き ま す 。 1 つ は 、 (cd に よ っ て ) デ ィ レ ク ト リ を 変 更 す る 方 法 、 も う 1 つ は .java フ ァ イ ル へ の パ ス を 完 全 指 定 す る 方 法 で す 。 相 対 パ ス は 、 現 在 の デ ィ レ ク ト リ か ら の 相 対 パ ス で す 。 ソ ー ス フ ァ イ ル を 渡 し た 場 合 、 −sourcepath オ プ シ ョ ン は 無 視 さ れ ま す 。 ア ス タ リ ス ク (*) の よ う な コ マ ン ド 行 ワ イ ル ド カ ー ド を 使 用 す る と 、 ク ラ ス の グ ル ー プ を 指 定 で き ま す 。

example% cd /home/src/java/awt
example% javadoc −d /home/html Button.java Canvas.java \
Graphics*.java

こ の 例 で は 、 ク ラ ス Button と Canvas、 お よ び 先 頭 が Graphics で 始 ま る ク ラ ス の HTML 形 式 の ド キ ュ メ ン ト が 生 成 さ れ ま す 。 javadoc の 引 数 と し て 渡 さ れ て い る の は 、 パ ッ ケ ー ジ 名 で は な く ソ ー ス フ ァ イ ル な の で 、 ド キ ュ メ ン ト は 、 ク ラ ス の リ ス ト と メ イ ン ペ ー ジ の 2 つ の フ レ ー ム を 持 つ こ と に な り ま す 。

example% cd /home/src/
example% javadoc −d /home/html java/awt/Button.java \
java/applet/Applet.java

こ の 例 で は 、 Button ク ラ ス お よ び Applet ク ラ ス 用 の HTML 形 式 の ド キ ュ メ ン ト が 生 成 さ れ ま す 。

example% javadoc −d /home/html /home/src/java/awt/Button.java \
/home/src/java/awt/Graphics*.java

こ の 例 で は 、 ク ラ ス Button お よ び 先 頭 が Graphics で 始 ま る ク ラ ス の HTML 形 式 の ド キ ュ メ ン ト が 生 成 さ れ ま す 。

パ ッ ケ ー ジ と ク ラ ス の ド キ ュ メ ン ト 化
パ ッ ケ ー ジ 全 体 と 個 々 の ク ラ ス を 同 時 に ド キ ュ メ ン ト 化 で き ま す 。 次 に 示 す の は 、 上 に 示 し た 2 つ の 例 を 組 み 合 わ せ た 例 で す 。 −sourcepath は 、 パ ッ ケ ー ジ へ の パ ス に 対 し て は 使 用 で き ま す が 、 個 々 の ク ラ ス の パ ス に 対 し て は 使 用 で き ま せ ん 。

example% javadoc −d /home/html −sourcepath /home/src java.awt \
/home/src/java/applet/Applet.java

こ の 例 で は 、 パ ッ ケ ー ジ java.awt と ク ラ ス Applet の HTML 形 式 の ド キ ュ メ ン ト が 生 成 さ れ ま す 。 javadoc は 、 Applet の パ ッ ケ ー ジ 名 を 、 Applet.java ソ ー ス フ ァ イ ル 内 の パ ッ ケ ー ジ の 宣 言 (宣 言 が あ る 場 合 ) か ら 決 定 し ま す 。

使 用 例
javadoc ツ ー ル に は 、 多 く の 便 利 な オ プ シ ョ ン が あ り 、 そ の 中 の い く つ か は 、 ほ か の オ プ シ ョ ン よ り も よ く 使 わ れ ま す 。 以 下 は 、 makefile 変 数 を 使 っ て Java プ ラ ッ ト フ ォ ー ム API 上 で javadoc ツ ー ル を 実 行 す る た め に 使 う 効 果 的 な コ マ ン ド で す 。 こ こ で は 180M バ イ ト の メ モ リ を 使 用 し て 、 Java 2 Platform, Standard Edition, v1.2 に 存 在 す る 、 約 1500 個 の public お よ び protected ク ラ ス に つ い て ド キ ュ メ ン ト を 生 成 し ま す 。

同 じ 例 を 2 回 掲 載 し ま す 。 最 初 の 例 は コ マ ン ド 行 か ら 実 行 す る も の で 、 2 番 目 の 例 は Makefile か ら 実 行 す る も の で す 。 オ プ シ ョ ン の 引 数 に 絶 対 パ ス を 使 用 し て い る た め 、 任 意 の デ ィ レ ク ト リ か ら こ の javadoc コ マ ン ド を 実 行 で き ま す 。

コ マ ン ド 行 の 例
次 の コ マ ン ド 行 の 例 は 900 文 字 を 超 え て い る た め 、 DOS な ど の シ ェ ル に は 大 き す ぎ ま す 。 こ の 制 限 を 回 避 す る に は 、 コ マ ン ド 行 引 数 フ ァ イ ル を 使 用 し ま す 。 ま た は 、 シ ェ ル ス ク リ プ ト を 記 述 し ま す 。

example% javadoc −sourcepath /jdk/src/share/classes .if n .ta 28n
−overview /java/jdk/src/share/classes/overview.html −d /jdk/build/api−use−splitIndex−windowtitle ’Java 2 Platform v1.2 API Specification’ −doctitle ’Java^{<font size="-2">TM</font>} 2 \

901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. \

−group "Core Packages" "java.*:com.sun.java.*:org.omg.*" −group "Extension Packages" "javax.*" .if n .ta 37

上 記 の コ マ ン ド で 、 packages は 、 処 理 対 象 の パ ッ ケ ー ジ 名 ( java.applett java.langな ど )が 入 っ て い る フ ァ イ ル の 名 前 で す 。 各 オ プ シ ョ ン の 、 単 一 引 用 符 で 囲 ま れ た 引 数 の 内 側 に は 、 改 行 文 字 を 挿 入 で き ま せ ん 。 た と え ば 、 こ の 例 を コ ピ ー ＆ ペ ー ス ト す る 場 合 は 、 −bottom オ プ シ ョ ン か ら 改 行 文 字 を 削 除 し て く だ さ い 。 さ ら に 、 こ の あ と の 「 注 」 も 参 照 し て く だ さ い 。

Makefile の 例
こ こ で は 、 GNU Makefile の 例 を 示 し ま す 。 Windows の Makefile の 例 に つ い て は 、 Windows の Makefile の 作 成 方 法 を 参 照 し て く だ さ い 。

−overview $ (SRCDIR)/overview.html /* Sets path for overview text */

WINDOWTITLE = ’Java Platform 1.2 Final API Specification’
DOCTITLE = ’Java^{<font size="-2">TM</font>} Platform 1.2 \
Final API Specification’
HEADER = ’<b>Java Platform 1.2</b><br><font size="-1">Final</font>’
BOTTOM = ’<font size="-1"><a href="http://java.sun.com/cgi-bin/\

bugreport.cgi">Submit a bug or feature</a><br><br>Java \
is a trademark or registered trademark of Sun \
Microsystems, Inc. in the US and other countries.<br>\
Copyright 1993-1998 Sun Microsystems, Inc. 901 San \
Antonio Road,<br>Palo Alto, California, 94303, U.S.A.\
</font>’
GROUPCORE = ’"Core Packages" "java.*:com.sun.java.*:org.omg.*"
GROUPEXT = ’"Extension Packages" "javax.*"’
SRCDIR = ’/java/jdk/1.2/src/share/classes’

Makefile の 引 数 は 、 単 一 引 用 符 で 囲 み ま す 。

注

こ の 例 で は 必 要 あ り ま せ ん が 、

−classpath お よ び −link も 重 要 な オ プ シ ョ ン で す 。

ト ラ ブ ル シ ュ ー テ ィ ン グ

一 般 的 な ト ラ ブ ル シ ュ ー テ ィ ン グ

エ ラ ー と 警 告
エ ラ ー メ ッ セ ー ジ お よ び 警 告 メ ッ セ ー ジ に は 、 フ ァ イ ル 名 と 宣 言 行 に 対 す る 行 番 号 が 含 ま れ ま す が 、 doc コ メ ン ト の 特 定 の 行 に 対 す る 行 番 号 は 含 ま れ ま せ ん 。

環 境

.:/home/classes:/usr/local/java/classes

関 連 項 目

javac(1)、 java(1)、 jdb(1)、 javah(1)、 javap(1)

次 に つ い て は 、 java.sun.com を 参 照 ま た は 検 索 し て く だ さ い 。
The Javadoc Home Page @

http://java.sun.com/products/jdk/javadoc/index.html

How to Write Doc Comments for Javadoc@

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

Setting the Class Path
How Javac and Javadoc Find Classes