🔸 TL;DR
▪️ Since Java 23, you can write Javadoc comments in Markdown.
▪️ Use /// instead of the traditional /** ... */.
▪️ Inline code becomes simple with backticks.
▪️ Code blocks become simple with triple backticks.
▪️ @param, @return, and other Javadoc tags still work.
▪️ The Javadoc tool converts the Markdown into HTML documentation.
🔸 The idea
Java 23 introduced a cleaner way to write Javadoc comments:
Markdown documentation comments using ///.
Not because classic Javadoc was “wrong”.
But because writing this:
feels a lot more natural than mixing Java comments, HTML tags, and Javadoc tags everywhere.
🔸 WHY IT MATTERS
Before Java 23, documenting code often meant writing things like:
It worked.
But it was noisy.
With Markdown Javadoc, the source code becomes easier to read, easier to write, and closer to what developers already use in README files, GitHub docs, and technical articles.
🔸 TAKEAWAYS
▪️ This is great for API documentation readability.
▪️ This makes examples in Javadoc less painful to maintain.
▪️ This lowers the friction for developers who avoid writing docs.
▪️ This does not remove classic HTML-based Javadoc.
▪️ This is useful when your project uses JDK 23+ tooling.
▪️ Be careful: /// is not a normal comment anymore in this context. It can become documentation.
Small feature.
Big developer experience improvement. 🚀
Sometimes modernization is not about adding more power.
Sometimes it is about removing friction.
#Java #JDK23 #Javadoc #Markdown #OpenJDK #JavaDeveloper #CleanCode #DeveloperExperience #Programming #SoftwareEngineering
Go further with Java certification:
Java👇
Spring👇
SpringBook👇
JavaBook👇