1概要
優れたAPIドキュメントは、ソフトウェアプロジェクトの全体的な成功に貢献する多くの要因の1つです。
幸い、最新版のJDKにはすべて、Javadocツールが用意されています。これは、ソースコードに含まれるコメントからAPIドキュメントを生成するためのものです。
前提条件:
-
JDK 1.4（最新バージョンのMavenにはJDK 7+が推奨されています）
Javadocプラグイン） 。 PATH 環境変数に追加されたJDK /bin フォルダー
-
（オプション）組み込みツールを備えたIDE
コメントから始めましょう。
-
Javadocのコメント構造は通常の複数行コメント** に非常に似ていますが、主な違いは冒頭の余分なアスタリスクです。
----//This is a single line comment
/**
** This is a regular multi-line comment
** //** **
** This is a Javadoc
** /----JavadocスタイルのコメントにはHTMLタグも含まれる可能性があります。
2.1. Javadocフォーマット
Javadocのコメントは、文書化したいクラス、メソッド、またはフィールドの上に置くことができます。
これらのコメントは一般的に2つのセクションから構成されています。
-
コメントしている内容の説明
-
独立したブロックタグ（“ @ ”記号が付いています）
特定のメタデータを記述する
この例では、より一般的なブロックタグをいくつか使用します。ブロックタグの一覧については、https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html[参照ガイド]を参照してください。
2.2. クラスレベルでのJavadoc
クラスレベルのJavadocコメントがどのようになるのかを見てみましょう。
----/** **
** Hero is the main entity we'll be using to . . .
**
** Please see the {@link com.baeldung.javadoc.Person} class for true identity
** @author Captain America
**
** /public class SuperHero extends Person {
//fields and methods
}
----簡単な説明と、独立型とインライン型の2つの異なるブロックタグがあります。
-
スタンドアロンタグは、最初のタグとして説明の後に表示されます。
行内の単語、たとえば @ author タグ インラインタグはどこにでも現れることがあり、中括弧で囲まれています
大括弧** 、たとえば説明の @ link タグ
この例では、2種類のブロックタグが使用されていることもわかります。
-
\ {@ link} は私達のソースの参照部分へのインラインリンクを提供します
コード ** @ author クラス、メソッド、またはフィールドを追加した作者の名前
それはコメントされています
2.3. Javadoc at Field Level
SuperHero クラス内で、このようなブロックタグなしで説明を使用することもできます。
----/** **
** The public name of a hero that is common knowledge
** /private String heroName;
----Javadocコマンドに -private オプションを明示的に渡さない限り、プライベートフィールドにはJavadocが生成されません。
2.4. Javadoc at メソッドレベル
メソッドにはさまざまなJavadocブロックタグを含めることができます。
私たちが使っている方法を見てみましょう。
----/** **
** <p>This is a simple description of the method. . .
** <a href="http://www.supermanisthegreatest.com">Superman!</a>
** </p>
** @param incomingDamage the amount of incoming damage
** @return the amount of health hero has after attack
** @see <a href="http://www.link__to__jira/HERO-402">HERO-402</a>
** @since 1.0
** /public int successfullyAttacked(int incomingDamage) {
//do things
return 0;
}
----successfullyAttacked メソッドには、説明と多数のスタンドアロンブロックタグの両方が含まれています。
適切なドキュメントを作成するのに役立つブロックタグがたくさんあります。さまざまな種類の情報を含めることができます。コメントに基本的なHTMLタグを利用することもできます。
上記の例で出くわしたタグを見てみましょう。
-
@ param は、メソッドのパラメータに関する有用な説明を提供します。
期待すべき入力 ** @ return は、メソッドが何を返すか、または返すことができるかについての説明を提供します。
-
@ see は \ {@ link} タグに似たリンクを生成しますが、もっと
インラインではなく参照のコンテキスト ** @ since は、クラス、フィールド、またはメソッドが追加されたバージョンを指定します
プロジェクトへ ** @ version はソフトウェアのバージョンを指定します。
％I％マクロと％G％マクロ ** @ throws は、ソフトウェアが実行するケースをさらに説明するために使用されます
例外を期待する ** @ deprecated は、コードが推奨されなくなった理由を説明します。
推奨されなくなった可能性があります。
どちらのセクションも技術的にはオプションですが、意味のあるものを生成するにはJavadocツールに少なくとも1つ必要です。
3 Javadoc Generation
Javadocページを生成するために、JDKに同梱されているコマンドラインツールとMavenプラグインを見てみましょう。
3.1. Javadocコマンドラインツール
Javadocコマンドラインツールは非常に強力ですが、複雑さも伴います。
オプションやパラメーターを指定せずに javadoc コマンドを実行すると、エラーが発生し、予期されるパラメーターが出力されます。
ドキュメントを生成するパッケージまたはクラスを少なくとも指定する必要があります。
コマンドラインを開いてプロジェクトディレクトリに移動しましょう。
クラスがすべてプロジェクトディレクトリの src フォルダにあるとします。
----[email protected]:~$ javadoc -d doc src\**
----これにより、- d フラグで指定された doc というディレクトリにドキュメントが生成されます。複数のパッケージまたはファイルが存在する場合は、それらすべてを提供する必要があります。
組み込み機能を持つIDEを利用することは、もちろん、より簡単で一般的にお勧めです。
3.2. JavadocとMavenプラグイン
Maven Javadocプラグインを利用することもできます。
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.0.0</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
<tags>
...
</tags>
</plugin>
</plugins>
</build>プロジェクトのベースディレクトリで、次のコマンドを実行してJavadocをtarget \ siteのディレクトリに生成します。
----[email protected]:~$ mvn javadoc:javadoc
----https://search.maven.org/classic/#search%7Cgav%7C1%7Cg%3A%22org.apache.maven.plugins%22%20AND%20a%3A%22maven-javadoc-plugin%22 ]は非常に強力で、複雑な文書生成をシームレスに容易にします。
生成されたJavadocページがどのようになるかを見てみましょう。
リンク:/uploads/overview-125x125.png%20125w[]
SuperHero クラスが拡張するクラスのツリービューを見ることができます。説明、フィールド、および方法を確認できます。詳細については、リンクをクリックしてください。
このメソッドの詳細図は次のようになります。
リンク:/uploads/ss__javadoc-1024x579-768x434.png%20768w[]
3.3. カスタムJavadocタグ
定義済みのブロックタグを使用してドキュメントをフォーマットするだけでなく、** カスタムブロックタグを作成することもできます。
そのためには、Javadocのコマンドラインに <tag name>:<locations-allowed>:<header> の形式で -tag__オプションを含めるだけです。
生成されたドキュメントの「Notable Locations」ヘッダーに表示される @ location allowedというカスタムタグを作成するには、以下を実行する必要があります。
----[email protected]:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\**
----このタグを使用するために、Javadocコメントのブロックセクションに追加することができます。
----/** **
** This is an example...
** @location New York
** @returns blah blah
** /----Maven Javadocプラグインは、 pom.xml でカスタムタグを定義することもできるほど柔軟です。
上記の同じタグをプロジェクトに設定するために、プラグインの <tags> セクションに次のコードを追加します。
...
<tags>
<tag>
<name>location</name>
<placement>a</placement>
<head>Notable Places:</head>
</tag>
</tags>
...これにより、毎回指定するのではなく、カスタムタグを1回指定することができます。
4結論
このクイックイントロダクションチュートリアルでは、基本的なJavadocを作成し、それらをJavadocコマンドラインで生成する方法について説明しました。
ドキュメントを生成するより簡単な方法は、組み込みのIDEオプションを使用するか、Mavenプラグインを pom.xml ファイルに組み込み、適切なコマンドを実行することです。
いつものように、コードサンプルはhttps://github.com/eugenp/tutorials/tree/master/core-java[over on GitHub]にあります。