Javadoc

Javadoc （ JavaDocまたはjavadocとも表記）は、Javaプログラミング言語用のAPI ドキュメント生成ツールです。Javadocは、Javaソースコード内の情報に基づいて、 HTML形式や拡張機能を利用した他の形式のドキュメントを生成します。[1] Javadocはサン・マイクロシステムズによって開発され、現在はオラクルが所有しています。

生成されるドキュメントの内容とフォーマットは、ソースコードコメント内の特別なマークアップによって制御されます。このマークアップはJavaコードのドキュメント化において事実上の標準であり広く使用されているため、 [2]多くのIDEはソースコードを表示しながらJavadoc情報を抽出して表示します。多くの場合、関連するシンボルにマウスを合わせることで表示されます。IntelliJ IDEA、NetBeans、Eclipseなどの一部のIDEは、Javadocテンプレートコメントブロックの生成をサポートしています。[3] Javadocマークアップの構文は、 Doxygen、JSDoc、EDoc、HeaderDocなどの他のドキュメント生成ツールによって再利用されています。@tag

Javadocはドックレットとタグレットによる拡張をサポートしており、これにより様々な出力形式の生成やコードベースの静的解析が可能になります。例えば、JDiffはAPIの2つのバージョン間の変更を報告します。

JavadocやAPIドキュメントジェネレータ全般を批判する人もいますが、Javadocを作成した動機の1つは、従来の（自動化されていない）APIドキュメントが古くなったり、テクニカルライターの不足などのビジネス上の制約により存在しなかったりすることが多いためです。[4]

JavadocはJavaの最初のリリース以来Javaの一部であり、Java開発キットのリリースごとに頻繁に更新されています。[5]

Javadoc および Javadoc で使用されるソース コードのコメントは、コンパイラによって無視されるため、Java 実行ファイルのパフォーマンスには影響しません。

マークアップ

Javadoc は、特別なマークが付けられていない限りコメントを無視します。Javadoc コメントは、複数行コメントの開始後に追加のアスタリスクでマークされます: /**。後続の行の先頭には が付き*、コメントブロック全体は で終了する必要があります*/。

メソッドの Javadoc コメントの例を次に示します。

/** * メソッドの動作の説明。* * @param input パラメータの説明。* @return 戻り値の説明。* @throws Exception 例外の説明。*/ public int methodName ( String input ) throws Exception { ... }

、、などの一部のHTMLタグはJavadocでサポートされています。[1]<p><head><nav>

マークダウン

Java 23以降、Javadocは古い複数行形式の代わりに、コメント行の先頭にMarkdown標準のCommonMarkをサポートしています。 [6]///

ドックレット

DocletプログラムはJavadocと連携して、ドキュメントに含めるコンテンツを選択し、コンテンツのプレゼンテーションをフォーマットし、ドキュメントを含むファイルを作成します。[7] DocletはJavaで記述されDoclet API、、

Javadocに含まれる[ StandardDoclet2]は、フレームベースのHTMLファイルとしてAPIドキュメントを生成します。他のドックレットはWeb上で入手可能であり[要出典]、多くの場合無料で利用できます。これらは以下の用途に使用できます。

タグ

利用可能なJavadocタグ[8]の一部を以下の表に示します。

構文使用法適用対象以来
@著者 名「Pat Smith」などの著者を識別しますクラス、インターフェース、列挙型
{ @docRoot }生成されたページから生成されたドキュメントのルートディレクトリへの相対パスを表しますクラス、インターフェース、列挙型、フィールド、メソッド
@version バージョンバージョン情報モジュール、パッケージ、クラス、インターフェース、列挙型
@since since-textこの機能が最初に存在した時期について説明しますクラス、インターフェース、列挙型、フィールド、メソッド
@ 参照ドキュメントの他の要素へのリンククラス、インターフェース、列挙型、フィールド、メソッド
@パラメータ 名の説明メソッドパラメータを記述する方法
@return の 説明戻り値について説明します方法
@exception クラス名 説明
@throws クラス名 説明		このメソッドからスローされる可能性のある例外について説明します方法
@非推奨の 説明メソッドを古いものとしてマークしますクラス、インターフェース、列挙型、フィールド、メソッド
{ @inheritDoc }オーバーライドされたメソッドから説明をコピーしますオーバーライドメソッド1.4.0
{ @link 参照}他のシンボルへのリンククラス、インターフェース、列挙型、フィールド、メソッド
{ @linkplain 参照}と同じですが{@link}、リンクのラベルがコードフォントではなくプレーンテキストで表示されます。クラス、インターフェース、列挙型、フィールド、メソッド
{ @value #STATIC_FIELD }静的フィールドの値を返す静的フィールド1.4.0
{ @code リテラル}コードフォントでリテラルテキストをフォーマットします。{@literal}クラス、インターフェース、列挙型、フィールド、メソッド1.5.0
{ @literal リテラル}リテラルテキストを表します。囲まれたテキストは、HTML マークアップやネストされた javadoc タグを含まないものとして解釈されます。クラス、インターフェース、列挙型、フィールド、メソッド1.5.0
{ @serial リテラル}デフォルトのシリアル化可能なフィールドを示します分野
{ @serialData リテラル}writeObject( )またはwriteExternal( )メソッドによって書き込まれたデータを示します分野、方法
{ @serialField リテラル}ObjectStreamFieldコンポーネントを示す分野

参照

参考文献

  1. ^ “Javadoc”. agile.csc.ncsu.edu . 2017年6月13日時点のオリジナルよりアーカイブ。2022年1月12日閲覧。
  2. ^ 「javadoc - Java APIドキュメントジェネレータ」. Sun Microsystems . 2011年9月30日閲覧。。
  3. ^ IntelliJ IDEA、NetBeans 2017年4月5日アーカイブ、Wayback MachineおよびEclipse
  4. ^ Venners, Bill; Gosling, James; et al. (2003-07-08). "Visualizing with JavaDoc". artima.com . 2013-01-19閲覧。オリジナルのコンパイラでオリジナルのJavaDocを作成したとき、私の周りの人たちでさえかなり厳しい批判を受けました。興味深いことに、よくある批判は「優秀なテクニカルライターならJavaDocよりもずっと良いものを作れる」というものだったからです。そして答えは「ええ、確かにそうですが、実際に優秀なテクニカルライターによってドキュメント化されたAPIはどれくらいあるでしょうか？そして、そのうちどれくらいの人が、役に立つほど頻繁にドキュメントを更新しているでしょうか？」です。
  5. ^ 「JavadocツールのDocコメントの書き方」Sun Microsystems . 2011年9月30日閲覧。。
  6. ^ 「JEP 467: Markdownドキュメントコメント」. OpenJDK . 2023年9月11日. 2025年9月10日閲覧。
  7. ^ 「ドックレットの概要」。
  8. ^ JavaSE 13 ドキュメントコメント仕様
  • Javadoc ツールのホームページ
  • Java プラットフォーム、Standard Edition Javadoc ガイド
  • JSR 260 Javadoc タグ技術更新Java 仕様要求(新しい Javadoc タグを定義)
  • ashkelonでJavadocを改善する
  • さまざまな Java ドキュメントを Windows ヘルプ形式に変換しました
Retrieved from "https://en.wikipedia.org/w/index.php?title=Javadoc&oldid=1316533963"