With the introduction of Markdown support in Javadoc comments in Java 23, developers should prefer Markdown syntax over legacy HTML tags (e.g.,
<b>, <i>, <code>, <ul>, <li>, etc.) and legacy Javadoc
tags (e.g. {@link java.util.HashMap}, {@code Object}).
Mixing HTML and Markdown can lead to readability issues and inconsistencies in rendering across tools. Markdown is generally more readable, less cluttered and, should be preferred over HTML tags when possible.
This rule will raise an issue when an HTML tag or a legacy Javadoc tag inside a markdown comment could be replaced with a slimmer, and more cohesive, syntax.
Here is a list of tags that should be replaced with markdown syntax:
<p> should be replaced with 2 new lines <code>MyCode</code>, {@code MyCode} should be replaced with `MyCode` <i>italic text</i>, <em> should be replaced with *italic text* <b>bold text</b>, <strong> should be replaced with **bold text** <ul><li>list item</li></ul>, <ol><li> should be replaced with * list
item {@link some.java.Class} should be replaced with [some.java.Class] {@link #equals(Object) equals} should be replaced with [equals][#equals(Object)]
/// This is a markdown Javadoc comment
/// <b>ExampleClass</b> is a simple utility for <i>demonstration purposes</i>.
/// <p>
/// Use <code>ExampleClass.run()</code> to execute the example.
/// </p>
/// {@link some.java.Class} for more details
public class ExampleClass {
}
/// This is a markdown Javadoc comment
/// **ExampleClass** is a simple utility for *demonstration purposes*.
///
/// Use `ExampleClass.run()` to execute the example.
/// [some.java.Class] for more details
public class ExampleClass {
}