はじめに

ちょっと前の話ですが、いつもみてるPublickey¹ に以下の記事がでました。
「Java 23」正式リリース。JavaDocのコメントでマークダウンが使えるように、ジェネレーショナルZGCがデフォルトになど新機能

「へえー、マークダウン使えるようになったんだ」ぐらいにしか思ってなかったのですが、せっかくなので具体的にどうなるのか調べてみた内容をメモがてら書いておきます

概要について

本件はJava 23で正式にリリースされた
Markdown Documentation Comments
の内容となります。

Markdown Documentation Commentsについて

本機能の目的は

Enable JavaDoc documentation comments to be written in Markdown rather than solely in a mixture of HTML and JavaDoc @-tags.

なので実際には

JavaDocドキュメントのコメントを、HTML と JavaDoc @ タグの混合ではなく、Markdown で記述できるようにします。

というように混合を回避して、シンプルにMarkdownだけで書けるようにしましょうという機能です。

実際の書き換え例が記載されていたので転記します。

旧JavaDocコメント

/**
 * Returns a hash code value for the object. This method is
 * supported for the benefit of hash tables such as those provided by
 * {@link java.util.HashMap}.
 * <p>
 * The general contract of {@code hashCode} is:
 * <ul>
 * <li>Whenever it is invoked on the same object more than once during
 *     an execution of a Java application, the {@code hashCode} method
 *     must consistently return the same integer, provided no information
 *     used in {@code equals} comparisons on the object is modified.
 *     This integer need not remain consistent from one execution of an
 *     application to another execution of the same application.
 * <li>If two objects are equal according to the {@link
 *     #equals(Object) equals} method, then calling the {@code
 *     hashCode} method on each of the two objects must produce the
 *     same integer result.
 * <li>It is <em>not</em> required that if two objects are unequal
 *     according to the {@link #equals(Object) equals} method, then
 *     calling the {@code hashCode} method on each of the two objects
 *     must produce distinct integer results.  However, the programmer
 *     should be aware that producing distinct integer results for
 *     unequal objects may improve the performance of hash tables.
 * </ul>
 *
 * @implSpec
 * As far as is reasonably practical, the {@code hashCode} method defined
 * by class {@code Object} returns distinct integers for distinct objects.
 *
 * @return  a hash code value for this object.
 * @see     java.lang.Object#equals(java.lang.Object)
 * @see     java.lang.System#identityHashCode
 */

新JavaDocコメント（マークダウン方式）

/// Returns a hash code value for the object. This method is
/// supported for the benefit of hash tables such as those provided by
/// [java.util.HashMap].
///
/// The general contract of `hashCode` is:
///
///   - Whenever it is invoked on the same object more than once during
///     an execution of a Java application, the `hashCode` method
///     must consistently return the same integer, provided no information
///     used in `equals` comparisons on the object is modified.
///     This integer need not remain consistent from one execution of an
///     application to another execution of the same application.
///   - If two objects are equal according to the
///     [equals][#equals(Object)] method, then calling the
///     `hashCode` method on each of the two objects must produce the
///     same integer result.
///   - It is _not_ required that if two objects are unequal
///     according to the [equals][#equals(Object)] method, then
///     calling the `hashCode` method on each of the two objects
///     must produce distinct integer results.  However, the programmer
///     should be aware that producing distinct integer results for
///     unequal objects may improve the performance of hash tables.
///
/// @implSpec
/// As far as is reasonably practical, the `hashCode` method defined
/// by class `Object` returns distinct integers for distinct objects.
///
/// @return  a hash code value for this object.
/// @see     java.lang.Object#equals(java.lang.Object)
/// @see     java.lang.System#identityHashCode

だいぶ、すっきりしてソースを直接みても読みやすくなりましたね！
またJavaDocコメントが

/**
 *
 */

が

///

というコメント形式になったのも大きな特徴かなと思います。
既存のJavaDocAPIに影響与えない配慮みたいです。

おわりに

Java23なので、この機能が実際に使われるようになるのは先になるかなと思いますがこの考え方自体はこれからの他の言語にも活かせそうな内容でした。

参考

https://openjdk.org/projects/jdk/23/
https://qiita.com/Sicut_study/items/9b20ac5ded003cb6d55a

https://www.publickey1.jp/ ↩