JEP 467，即“Markdown文档注释”，已从“提议目标”转变为 JDK 23 的“目标”。此功能提议允许将 JavaDoc 文档注释写成 Markdown，而不是混合使用 HTML 和 JavaDoc @ 标签，旨在简化在 Java 源代码中编写和阅读文档注释的过程。
Java 23支持Markdown
主要目标此更新的主要目标是简化创建和理解文档注释的过程。由于 Markdown 的简单性和可读性，它是 HTML 和 JavaDoc 标签的优越替代品。此更改将确保现有的文档注释不受影响，从而保持向后兼容性。
Markdown 的优势Markdown 是一种以轻量级著称的标记语言，易于使用。它支持基本的文档结构，如段落、列表、样式化文本和链接。与 HTML 相比，HTML 书写和理解起来较为繁琐，而 Markdown 的语法简单明了，使其对开发者更具可读性和可操作性。对于 Markdown 不直接支持的结构，可以包含 HTML，从而在降低复杂性的同时提供灵活性。
实现细节Markdown 文档注释将使用 /// 在每行的开头标识，而不是传统的 /** ... */ 语法。这种方法可以避免与示例中的嵌入式 /* ... */ 注释冲突，这在文档注释中越来越常见。
Markdown 的解析将使用 CommonMark 变体，并增强其功能以支持链接到程序元素和简单的 GitHub 风格的 Markdown (GFM) 表格。Markdown 注释中仍可以使用 JavaDoc 标签，以确保保留现有的 JavaDoc 功能。
编译器树 API 将扩展以有效处理 Markdown 内容，引入一种新的树节点类型 RawTextTree，以及一种新的树节点种类 DocTree.Kind.MARKDOWN。将利用 commonmark-java 库将 Markdown 转换为 HTML。
对开发者的影响此更新不包括现有文档注释向 Markdown 的自动转换。开发者需要手动更新他们的文档以利用新功能。
通过采用 Markdown 进行 JavaDoc 注释，此增强功能预计将提高开发者的生产力和 Java 文档的整体可读性。它标志着 Java 文档能力的重要进步，使开发者更易于维护和改进代码文档。
总之，JEP 467 引入的 Markdown 支持代表了一个重大改进，承诺提供一种更易于访问和维护的 Java 代码文档方法。
传统格式：
/** * 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 {@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 */Markdown格式
/// 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 `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