javadocツールの標準ドックレットでは、ドキュメント・コメントでのMarkdownのCommonMarkバリアントの使用と、プログラム要素に対するJavaDocタグおよびリンクの拡張がサポートされています。

Markdownを使用してドキュメント・コメントを記述するには、3つのスラッシュ(///)で始まる連続した行末コメント(JLS: 3.7 コメントを参照)を使用します。その後、コメントの内容は次のように決定されます:

• 先頭の空白と最初の3つのスラッシュ(/)文字は、各行から削除されます。

• 先頭の空白文字を削除して、行は左にシフトされます。これは、最も少ない先頭の空白文字を持つ空白ではない行に、先頭の空白文字が残らなくなるまで行われます。

• 各行にある追加の先頭の空白文字と、末尾の空白文字は保持されます。

一連の行は連続している必要があります。コメントに空白行を含めるには、オプションの空白で始まり、次に///が続く必要があります。完全な空白行を指定すると、前後のコメントは個別のコメントとして扱われます。その場合、最後のコメント以外はすべて破棄され、最後のコメントのみが後続の宣言のドキュメント・コメントとみなされます。

例:

/// This is the traditional "Hello World!" program.
public class HelloWorld {
    public static void main(String... args) {
        System.out.println("Hello World!");
    }
}

/// This is the traditional _"Hello World!"_ program.

<p>This is the traditional <em>"Hello World!"</em> program.</p>

APIの他の場所で宣言された要素へのリンクを作成するには、Markdown参照リンクの拡張形式を使用できます。この参照のラベルは、要素自体への参照から導出されます。

テキストが要素のIDから導出されるリンクを作成するには、要素への参照を大カッコで囲みます。たとえば、java.util.Listにリンクするには、[java.util.List]を記述するか、コードにjava.util.Listのimport文がある場合は[List]のみを記述します。リンクのテキストは等幅フォントで表示されます。リンクは、標準のJavaDoc {@link ...}タグを使用する場合と同じです。

/// * a module [java.base/]
/// * a package [java.util]
/// * a class [String]
/// * a field [String#CASE_INSENSITIVE_ORDER]
/// * a method [String#chars()]

代替テキストを含むリンクを作成するには、[text][element]という形式を使用します。たとえば、a listというテキストを含むjava.util.Listへのリンクを作成するには、[a list][List]を記述します。リンクは現在のフォントで表示されますが、指定されたテキスト内では書式設定の詳細を使用できます。リンクは、標準のJavaDoc {@linkplain ...}タグを使用する場合と同じです。

例:

/// * [the `java.base` module][java.base/]
/// * [the `java.util` package][java.util]
/// * [a class][String]
/// * [a field][String#CASE_INSENSITIVE_ORDER]
/// * [a method][String#chars()]

配列パラメータを持つメソッドへの参照リンクを作成するには、参照内の大カッコをエスケープする必要があります。たとえば、メソッドString.copyValueOf(char[])への参照リンクを次に示します:

[String#copyValueOf(char\[\])]

生成されたドキュメントでユーザー定義のIDおよび暗黙的に定義されたIDへのリンクを作成するには、##表記法を使用します。たとえば、Java SEクラスMemoryLayoutには、対応するアンカーaccess-mode-restrictionsを持つAccess mode restrictionsという見出しがあります。次の例は、そのアンカーへのリンクを示しています:

/// link to [access mode restrictions][MemoryLayout##access-mode-restrictions]

他の形式のMarkdownリンクを使用することもできますが、通常、他のプログラム要素へのリンクは最も一般的です。

単純な表は、GitHub Flavored Markdown Specで定義されている構文を使用してサポートされます。たとえば、単純な表は次のように記述できます:

/// | Latin | Greek |
/// |-------|-------|
/// | a     | alpha |
/// | b     | beta  |
/// | c     | gamma |

アクセシビリティに必要となる可能性のあるキャプションおよびその他の機能は、サポートされていません。そのような場合、引き続きHTML表を使用することをお薦めします。

JavaDocタグでは、インライン・タグ({@inheritDoc}など)とブロック・タグ(@paramや@returnなど)の両方をドキュメント・コメントで使用できますが、どちらもコード・スパン(バッククォート内で囲まれたインライン・テキスト)やコード・ブロック(インデントされたコード・ブロック、または3つのバッククォート(```)や3つのチルダ(~~~)などのフェンス内で囲まれたテキストのブロック)などのリテラル・テキスト内では使用できません。

/// {@inheritDoc}
/// In addition, this methods calls [#wait()].
///
/// @param i the index
public void m(int i) ...

次の例は、文字シーケンス@...および{@...}がコード・スパンおよびコード・ブロック内で特別な意味を持たないことを示しています:

/// The following code span contains literal text, and not a JavaDoc tag:
/// `{@inheritDoc}`
///
/// In the following indented code block, `@Override` is an annotation,
/// and not a JavaDoc tag:
///
///     @Override
///     public void m() ...
///
/// Likewise, in the following fenced code block, `@Override` is an annotation,
/// and not a JavaDoc tag:
///
/// ```
/// @Override
/// public void m() ...
/// ```

マークアップ付きのテキストを含むタグの場合、Markdownドキュメント・コメントでは、そのマークアップもMarkdown形式になります。

たとえば、JavaDoc @paramタグ内でのMarkdownの使用を次に示します:

/// @param the list, or `null` if no list is available

{@inheritDoc}タグは、1つ以上のスーパータイプからメソッドのドキュメントを含めるために使用されます。タグを含むコメントの形式は、継承されるドキュメントを含むコメントの形式と同じである必要はありません。

例:

interface Base {
    /** A method. */
    void m()
}

class Derived implements Base {
    /// {@inheritDoc}
    public void m() { }
}

ユーザー定義のJavaDocタグは、Markdownドキュメント・コメントおよび標準のJavaDocタグで使用できます。たとえば、JDKドキュメントでは、{@jls ...}が使用され、Java言語仕様(JLS)へのリンクの短い形式として定義されています。また、@implSpecや@implNoteなどのブロック・タグには、特定の情報のセクションが導入されています。

/// For more information on comments, see {@jls 3.7 Comments}.
///
/// @implSpec
/// This implementation does nothing.
public void doSomething() { }

コード例は、Markdownのコード・スパンやコード・ブロックを使用するか、{@snippet …}タグを使用して、ドキュメント・コメントに含めることができます。コード・スパンやコード・ブロックは簡単でわかりやすい一方で、スニペット・タグは、生成されたドキュメント内の他のプログラム要素へのリンクなどの追加機能を提供します。

従来のコメントの使用(JLS: 3.7 コメントを参照)とは対照的に、各行の///の後に配置できる文字に制限はありません。特に、行末コメントでの*/の使用に対する制限はありません。

たとえば、ソース・コード例には、次のいずれかのコメントを含めることができます:

/// Here is an example of how to use this method.
/// 
/// /* get the next random number */
/// var i = rgen.nextInt(); 
/// 
int nextInt();

/// Here is an example of how to use this method.
/// 
/// // get the next random number
/// var i = rgen.nextInt(); 
/// 
int nextInt();

文字*/は、正規表現を含む例にも配置できます:

/// 
/// // Find all strings ending in '.*/'
/// return strings.stream().filter(s-> s.matches(".*/"));
/// 

これらの文字は、glob式を含む例にも配置できます:

/// ```
/// // Find all paths for .txt files in home directories.
/// return Files.newDirectoryStream(dir, "/home/*/*.txt");
/// ```

/// This is the traditional <span id="hw">Hello World!</span> program.

ソース・コードに使用される文字セット以外の文字には、HTMLエンティティを使用することもできます:

/// This is the traditional “Hello World!” program.

HTMLブロック内ではMarkdown構文が認識されないことに注意してください。ただし、HTMLブロック間の段落またはその他のブロックではMarkdown構文を使用できます。詳細は、CommonMark仕様のHTMLブロックおよびRaw HTMLに関する項を参照してください。JavaDocタグは、HTMLブロックでサポートされています。

doc-filesサブディレクトリのMarkdownファイルは、このようなディレクトリ内のHTMLファイルと同様に適切に処理されます。このようなファイルのJavaDocタグは処理されます。ページ・タイトルは最初の見出しから推測されます。PandocのMarkdownプロセッサでサポートされているようなYAMLメタデータ(Pandocユーザーズ・ガイドのPandocのMarkdownに関する項を参照)はサポートされていません。

生成されたトップレベル(概要)ページの内容を含むファイルは、Markdownファイルでもかまいません。

JavaDocタグの使用を除き、Markdownドキュメント・コメント内の他の文字列は、有効なCommonMarkドキュメントです。つまり、作成者が不適切な形式のMarkdown構成要素とみなす可能性のある文字列に関するエラーはレポートされません。通常、このような文字列は、生成された出力にプレーン・リテラル・テキストとして表示されます。

Markdownドキュメント・コメントのJavaDocタグの使用で検出された問題によって、診断メッセージがコンソールまたは特徴的なコンテンツにレポートされ、次のように生成されたドキュメントに配置される場合があります:

HTMLソース	レンダリングされたHTML
<span style="border:1px solid black; background-color:#ffe6e6; padding: 2px">&#x25B6; invalid @code</span>

従来の(Markdown以外の)ドキュメント・コメントと同様に、作成者は、ドキュメント・コメントからjavadocによって生成されたドキュメントを注意深く校正し、生成された出力が意図したとおりであることを確認するようお薦めします。