Loading article…
Javadoc （ JavaDocまたはjavadocとも表記される）は、Javaプログラミング言語用のAPIドキュメント生成ツールです。Javaソースコードの情報に基づいて、JavadocはHTML形式および拡張機能によるその他の形式のドキュメントを生成します。[ 1 ] JavadocはSun Microsystemsによって作成され、現在はOracleが所有しています。
生成されるドキュメントの内容と書式は、ソースコードコメント内の特別なマークアップによって制御されます。このマークアップは、Java コードのドキュメント化において事実上の標準であり、広く普及しているため、 [ 2 ]多くのIDE は、ソースコードを表示しながら Javadoc 情報を抽出して表示します。多くの場合、関連するシンボルにマウスカーソルを合わせることで表示されます。IntelliJ IDEA、NetBeans、Eclipseなどの一部の IDE は、Javadoc テンプレート コメント ブロックの生成をサポートしています。[ 3 ] Javadoc マークアップの構文は、 Doxygen、JSDoc、EDoc、HeaderDocなどの他のドキュメント ジェネレーターによって再利用されています。@tag
Javadocは、ドクレットとタグレットによる拡張をサポートしており、さまざまな出力形式を生成したり、コードベースの静的解析を実行したりできます。例えば、JDiffはAPIの2つのバージョン間の変更点をレポートします。
JavadocやAPIドキュメントジェネレータ全般を批判する人もいるが、Javadocを作成した動機の一つは、より従来型の（自動化されていない）APIドキュメントは、技術ライターの不足などのビジネス上の制約により、しばしば古くなったり、存在しなかったりすることであった。[ 4 ]
JavadocはJavaの最初のリリース以来Javaの一部であり、Java Development Kitの各リリースで頻繁に更新されています。[ 5 ]
JavadocおよびJavadocで使用されるソースコードコメントは、コンパイラによって無視されるため、Java実行可能ファイルのパフォーマンスには影響しません。
Javadoc は、特別なマークが付けられていない限りコメントを無視します。Javadoc コメントは、複数行コメントの開始後にアスタリスクを追加してマークします。/**。以降の行には が付き*、コメントブロック全体は で終了する必要があります*/。
メソッドのJavadocコメントの例を以下に示します。
/** * メソッドの動作の説明。* * @param input パラメータの説明。* @return 戻り値の説明。* @throws Exception 例外の説明。*/ public int methodName ( String input ) throws Exception { ... }Javadocでは、<p>、<p>、<p>などの一部のHTMLタグがサポートされています。<p><head><nav>
Java 23以降、Javadocは、以前の複数行形式ではなく、で始まるコメント行でMarkdown標準のCommonMarkをサポートしています。 [ 6 ]///
Doclet プログラムは Javadoc と連携して、ドキュメントに含めるコンテンツを選択し、コンテンツの表示形式を整え、ドキュメントを含むファイルを作成します。[ 7 ] Doclet は Java で記述されDoclet API、
のStandardDocletJavadocに付属する機能は、フレームベースのHTMLファイルとしてAPIドキュメントを生成します。その他のDocletはWeb上で入手可能で、多くの場合無料です。これらは以下の目的で使用できます。
利用可能なJavadocタグ[ 8 ]の一部を以下の表に示します。
私がオリジナルのコンパイラでオリジナルの JavaDoc を作成したとき、私の身近な人たちでさえ、かなり厳しく批判しました。そして興味深いことに、よくある批判は、優秀なテクニカル ライターなら JavaDoc よりずっと良いものを書けるだろう、というものでした。そして答えは、まあ、そうですが、実際に優秀なテクニカル ライターによって文書化されている API はいくつありますか? そして、実際に役に立つほど頻繁にドキュメントを更新している API はいくつありますか?