Java 23の新機能「JEP 467: Markdown Documentation Comments」の内容を確認してみた

# はじめに

ちょっと前の話ですが、いつもみてるPublickey[^1] に以下の記事がでました。
[「Java 23」正式リリース。JavaDocのコメントでマークダウンが使えるように、ジェネレーショナルZGCがデフォルトになど新機能](https://www.publickey1.jp/blog/24/java_23javadoczgc.html)

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

# 概要について

本件はJava 23で正式にリリースされた
[Markdown Documentation Comments](https://openjdk.org/jeps/467)
の内容となります。

# 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

[^1]: https://www.publickey1.jp/