TL;DR overview
- Java 23 introduces Markdown-formatted documentation comments, allowing developers to write Javadoc using familiar Markdown syntax alongside traditional HTML Javadoc tags.
- This change makes API documentation easier to write and read in source code, reducing the friction of maintaining accurate and well-formatted Javadoc across large Java projects.
- Sonar has updated its Java analyzer to recognize and correctly parse Markdown doc comments, ensuring documentation rules and violations are accurately detected in Java 23 codebases.
- Teams upgrading to Java 23 can adopt Markdown comments incrementally—existing Javadoc remains valid—while taking advantage of cleaner syntax for new and updated documentation.
Welcome back to our blog series on the latest Java features, documentation, and the new rules in SonarQube designed to check for the proper usage of javadoc and markdown, ensuring your code adheres to best practices and avoids common pitfalls.
We’ve covered Java 22, and are now getting into Java 23, which introduces several new language features. We’ll focus on enhancing documentation, and how to leverage the new features with simple examples.
What is JavaDoc and Markdown?
Java 23 introduces an enhancement to JavaDoc, allowing comments that begin with three slashes `///` to be interpreted as JavaDoc comments using Markdown syntax. This subtle yet significant change aims to simplify the process of writing rich and readable documentation directly within the code. By leveraging Markdown, developers can more easily format their JavaDoc comments with features like bold text, italics, lists, and code blocks, without needing to learn specific JavaDoc HTML tags, officially detailed in JEP 445. This streamlines the documentation process, making it more intuitive and encouraging the creation of better-formatted and more accessible API documentation.
SonarQube has introduced new rules to assist developers in adopting Java 23's Javadoc and Markdown enhancements. These rules — including S7476 and S7474 — ensure that documentation is consistently formatted, easy to read, and free from common migration pitfalls. By leveraging these rules, developers can seamlessly integrate Markdown into their Javadoc comments to improve clarity and maintainability, ensuring that the old code is completely aligned with the new features.
Rule S7476: Comments should not start with more than two slashes
With Java 23, comments starting with /// are now officially interpreted as Javadoc comments that use Markdown syntax. Before, they were simply ignored by the Javadoc tool and treated as regular implementation comments. This change means that existing comments in your codebase could unintentionally become part of your public API documentation after migrating to Java 23. This can lead to confusing or unprofessional-looking documentation and increases the effort required for migration. This new rule helps you find these cases in advance so they can be corrected.
Noncompliant Code Example:
public class Calculator {
/////////////////////////////////////////////
// A section for advanced math operations. //
// These are experimental. //
/////////////////////////////////////////////
public int add(int a, int b) {
/// This is a super important implementation note for the add method.
/// It should not be in the final Javadoc.
return a + b;
}
}In the example above, both the decorative block comment and the /// comment would be incorrectly processed as Javadoc in Java 23.
Compliant Solution:
public class Calculator {
// A section for advanced math operations.
// These are experimental.
public int add(int a, int b) {
// This is a super important implementation note for the add method.
// It should not be in the final Javadoc.
return a + b;
}
}The compliant solution is to ensure regular comments use the standard // syntax.
Rule S7474: Markdown, HTML and Javadoc tags should not be mixed
Java 23's introduction of Markdown in Javadoc comments is a significant step towards cleaner, more readable documentation. To maintain consistency, it's best to fully embrace Markdown syntax and avoid mixing it with legacy HTML tags (like <b>, <code>, <li>) or old Javadoc block tags (like {@code} or {@link}). Mixing these styles can lead to inconsistent rendering across different tools and makes the raw documentation harder to read. This rule encourages developers to use the modern, more concise Markdown syntax wherever possible.
Noncompliant Code Example:
///
/// A utility class for <b>String</b> operations.
/// <p>
/// Use this class to perform common manipulations. For more details,
/// see {@link java.lang.String}.
/// You can also use {@code new StringManipulator()}.
///
public class StringManipulator {
// ...
}This Javadoc mixes bold HTML tags with Javadoc's {@link} and {@code} tags. The clean, modern approach is to use Markdown for all formatting.
Compliant Solution:
///
/// A utility class for **String** operations.
///
/// Use this class to perform common manipulations. For more details,
/// see [String].
/// You can also use `new StringManipulator()`.
///
public class StringManipulator {
// ...
}By adopting a consistent Markdown style, your documentation becomes cleaner, easier to write, and future-proof.
How Java 23 and SonarQube work together
By embracing the new features in Java 23 — such as Markdown in Javadoc — developers can write more efficient, and more maintainable code resulting in a higher-quality code. However, staying abreast of these evolving language enhancements and consistently applying best practices can be challenging.
This is where tools like SonarQube, become invaluable. They provide automated checks that help ensure your code not only leverages these modern features correctly but also adheres to high-quality standards, ultimately improving code clarity and overall project quality.
