Write Doc Comments in Markdown
class Inventory {
/**
* Returns the supplies that run out before a mission day.
* <p>
* A supply runs out when its <em>daily consumption</em>
* times the mission day exceeds its stock.
* <ul>
* <li>The result is sorted by name.</li>
* <li>An empty list means the stock lasts.</li>
* </ul>
* <p>
* Example:
* <pre>{@code
* var missing = inventory.runningOutBefore(30);
* }</pre>
*
* @param missionDay the day to check, from {@code 1}
* @return the supplies that run out, never {@code null}
* @see Supply#dailyConsumption()
*/
List<Supply> runningOutBefore(int missionDay) {
return List.of();
}
record Supply(String name, int stock, int dailyConsumption) {}
}Classic Javadoc is HTML inside a /** */ block. Tags like <p>, <ul>, <li>, <em>, and <pre>{@code} drown the actual text in markup.
That's a pity, because you read doc comments in the editor far more often than in the generated documentation. And there, all this markup makes them hard to read and tedious to write.
class Inventory {
/// Returns the supplies that run out before a mission day.
///
/// A supply runs out when its _daily consumption_
/// times the mission day exceeds its stock.
///
/// - The result is sorted by name.
/// - An empty list means the stock lasts.
///
/// Example:
/// ```
/// var missing = inventory.runningOutBefore(30);
/// ```
///
/// @param missionDay the day to check, from `1`
/// @return the supplies that run out, never `null`
/// @see Supply#dailyConsumption()
List<Supply> runningOutBefore(int missionDay) {
return List.of();
}
record Supply(String name, int stock, int dailyConsumption) {}
}Since Java 23 (JEP 467), doc comments that start with /// are written in Markdown. A blank line replaces <p>, a - replaces <ul><li>, underscores replace <em>, backticks replace {@code}, and a fenced code block replaces <pre>.
Block tags like @param, @return, and @see, as well as links to program elements, still work. The comment reads well in the source and renders just the same in the generated documentation.
You don't have to convert everything at once: both styles can be mixed in the same file, so you can migrate one comment at a time.
