Why is this an issue?

Starting in Java 23, comments beginning with three slashes /// are interpreted as JavaDoc comments using Markdown syntax.

In Java 22 and earlier, comments starting with more than 2 slashes were treated as normal comments. Accidentally writing comments with three or more slashes can lead to unintended JavaDoc being generated, when migrating to Java 23.

What is the potential impact?

Comments starting with three or more slashes will increase the migration cost when upgrading to Java 23 or later. Moreover, IDE or other tools may handle such comments as JavaDoc comments if they are not aware of the Java version.

Exceptions

• The rule does not raise issues on license headers at the start of files because they will not be considered as JavaDoc comments.
• The rule only raises issues in projects using Java 17 or above, because those projects will likely be migrated to Java 23 or later.

How to fix it

In versions of Java prior to 23, comments should not start with more than 2 slashes, and from Java 23 forward they should not start with more than 3.

Code examples

Noncompliant code example

The following code will generate unintended JavaDoc comments if migrated to Java 23:

/// Some comment for the developers
public abstract void foo();
//// public void foo(String s){}
public void foo(){}

Compliant solution

// Some comment for the developers
public abstract void foo();
// public void foo(String s){}
public void foo(){}

Resources

Documentation

• OpenJDK - JEP 467: Markdown Documentation Comments