Markdown in Java Docs? Shut Up and Take My Comments!

/**
  * 
Fetches a random cat fact from the API.
  * 
Features:
  * 

  *     
Fetches a cat fact
  *     
Uses a remote API
  *     
Returns a simple String
  * 
  * @return A random cat fact
  * @throws IOException If the API call fails
  */

You stare at the screen. Did you just write documentation or bring back some old HTML nightmare?

Now, enter Markdown (easier to write and read):

/// Fetches a **random cat fact** from the API.
///
/// **Features:**
///
/// - Fetches a cat fact
/// - Uses a remote API
/// - Returns a simple `String`
///
/// @return A random cat fact
/// @throws IOException If the API call fails

No more HTML torture. As a developer, you should focus on writing code, not debugging documentation like it’s a broken HTML page from 1998. HTML was cool and great in the late 90s and early 2000s, but not so much now. 

This blog post explores what Markdown documentation comments are, why and how us developers should use them, and how IntelliJ IDEA supports this feature. 

What Are Markdown Documentation Comments?

In Java 23 and later versions, you can use the CommonMark variant of Markdown to write documentation comments in your Java source files. Until Java 22, Javadoc comments could only be written using a combination of HTML and JavaDoc tags. Now you could use any of these styles, including using JavaDoc tags with Markdown.

If you are wondering why Markdown? Think of the familiar Readme.md for your favorite repository on Github, which is written using Markdown. It is widely used for documentation, README files, and online content due to its simplicity and compatibility. My friends have used Markdown to write books too. Its lightweight syntax prevents formatting errors that could break pages or waste debugging effort and it could be converted to HTML and other formats if required. 

Markdown allows you to include inline and block code snippets in your documentation, including code blocks that might include multi line comments Multiline comments end with */, and it is not easy to include them when you use the /**…*/ style to write the documentation comments (examples included in this post).

Documentation comments vs. multiline comments

If you are a new developer, are you wondering whether multiline comments are the same as documentation comments? They are not. Multi-line comments (/* … */) are for longer explanations or temporarily disabling blocks of code. On the other hand, Documentation comments (/** … */ and ///) are stylized comments that you use to document your code. They are special types of comments that can be processed by JavaDoc (JDK tool) to generate HTML documentation.

Documentation comments also show up in your IntelliJ IDEA’s editor window when you select ‘Quick Documentation’ or just navigate to the source file. Including documentation comments within a Java class ensures that the documentation of your codebase evolves with the code, keeping it relevant. 

Markdown documentation comments start with triple forward slashes, that is, ///. Let’s look at an example.

An example

Markdown documentation comments start a triple forward slashes, that is, ///. Following is example of a Javadoc comment in Markdown that you could use to document the purpose of a class (it includes more element types that the one used in the beginning of this blog post :) ):

/// This class demonstrates practical usage of Markdown in Javadoc for a real-world application.
///
/// ## Features
/// - User creation and management
/// - Role-based access control
/// - Secure password handling
///
/// ## Architecture
///
/// The system follows a layered architecture:
/// 1. **Presentation Layer** - Handles user interface
/// 2. **Service Layer** - Contains business logic
/// 3. **Data Access Layer** - Manages data persistence
///
/// @author Mala Gupta
/// @version 1.0
/// @see UserRole

Though this documentation is already more readable than similar comments that might use HTML tags, IntelliJ IDEA can improve the readability further.

How IntelliJ IDEA supports this feature

IntelliJ IDEA supports this feature for you developers in multiple ways. Let’s start with the Reader Mode.

Reader mode in IntelliJ IDEA

With its Reader Mode, IntelliJ IDEA can render your comments in a format that is more readable. You can either use the gutter icon to change the view, or use the shortcut for the feature ‘Toggle Rendered View’, as shown below:

The reader mode works with the Javadoc comments written in HTML too. You could also use it to enable inlay hints, adjust line height of the rendered comments, and more. Check out this link for details.

Modify the size of the rendered comments

To increase or decrease the font size of the comments, right click anywhere inside the comments and use the option ‘Adjust font size..’, as shown below:

IntelliJ IDEA offers more support for Markdown Javadoc comments than just showing them in a more readable format.

Converting to Markdown Documentation comment in IntelliJ IDEA

IntelliJ IDEA can detect documentation comments that are written using HTML tags and offer them to be converted to Markdown, via its context action ‘Convert to Markdown documentation comment’, for your convenience, as shown below:

You could also run the inspection ‘Javadoc comment can be Markdown documentation comment’, on your project folder to view and convert all Javadoc comments to markdown, as shown in the following gif:

JDK version for using Markdown documentation comments in IntelliJ IDEA

Your organisation might not be using the latest Java version (for obvious reasons). But that doesn’t mean you can’t use this amazing feature in your code base with IntelliJ IDEA. Using markdown for documentation comments was added in JDK version 23, but you could use markdown in documentation comments in IntelliJ IDEA with earlier Java language levels too, as shown in the following gif:

However, if you try to use a previous version of JDK and its Javadoc utility to generate documentation comments, the ones written using markdown won’t be recognized.

View Documentation comments without losing your coding flow

Often while using a class, I take a sneak peek at its documentation to understand how it works, without navigating to its source code (so that I don’t lose my coding flow). In IntelliJ IDEA, you could use ‘Quick Documentation’ feature to do so:

Depending on where your cursor is, IntelliJ IDEA will show you the documentation of a class, constructor or a method.

More examples of using Markdown documentation comments 

Let’s work with more examples of how you can use the simple markups in markdown to write Javadoc comments. Each of the following sections includes the Markdown documentation comments and how it can be viewed in IntelliJ IDEA via its Reader mode.

Basic Text Formatting 

This section demonstrates basic text formatting in Markdown, such as, text in boldface, italic, inline code, a horizontal line, or escaping characters using backslash:

/// ## Inline Formatting
/// - **Bold text** is created using double asterisks or double underscores
/// - *Italic text* is created using single asterisks or single underscores
/// - ***Bold and italic*** is created using triple asterisks
/// - `Inline code` is created using backticks
/// - Subscript is created using HTML sub tags
/// - Superscript is created using HTML sup tags
///
/// ## Horizontal Rule
/// A horizontal rule can be created using three or more asterisks or underscores:
/// ***
///
/// ## Escaping Special Characters
/// You can escape special characters using a backslash:
/// \*This text is not in italics\*
///
/// @return A string indicating successful demonstration

Headings in Markdown

You might prefer to use different levels of headings to structure larger documentation comments. Markdown supports different heading levels, as shown below:

/// # Heading 1
/// ## Heading 2
/// ### Heading 3
/// #### Heading 4
/// ##### Heading 5
/// ###### Heading 6
///
/// Alternatively, you can use the following syntax for heading 1 and 2:
///
/// Heading 1
/// =========
///
/// Heading 2
/// ---------
///
/// @param level The heading level to demonstrate (1-6)
/// @return A string representation of the heading
public String headingsExample(int level) {
    return "Heading level " + level + " demonstrated";
}

Lists in Markdown

Markdown supports both ordered and unordered lists. Task list that allows you to put a cross for completed tasks is interesting too: 

/// ## Unordered Lists
/// - Item 1
/// - Item 2
///   - Subitem 2.1
///   - Subitem 2.2
/// - Item 3
///
/// You can also use asterisks or plus signs:
/// * Item A
/// * Item B
/// + Item X
/// + Item Y
///
/// ## Ordered Lists
/// 1. First item
/// 2. Second item
///    1. Subitem 2.1
///    2. Subitem 2.2
/// 3. Third item
///
/// ## Task Lists
/// - [x] Completed task
/// - [ ] Incomplete task
/// - [x] Another completed task
///
/// @param items The list of items to process
/// @return A processed list of items

public List listsExample(List items) {
    // Implementation details omitted
    return items;
}

Code Blocks in Markdown

Markdown allows you to include inline and block code snippets in your documentation, including code blocks that might include multi line comments Multiline comments end with ‘*/’, and it is not easy to include them when you use the /**…*/ style to write the documentation comments. Markdown helps with syntax highlighting too.

/// ## Inline Code
/// Use backticks for `inline code` elements.
///
/// ## Fenced Code Blocks
/// ```java
/// /*
///  *  Look ma! No public classes 
///  *  and public static void main(String[] args)
///  *  Just to print a value to console
///  */
///  void main() {
///     println("Hello, Markdown!");
///  }
/// ```
///
/// ## Syntax Highlighting
/// ```javascript
/// function greet(name) {
///     console.log(`Hello, ${name}!`);
/// }
/// ```
///
/// ```sql
/// SELECT * FROM users WHERE age > 18;
/// ```

Links and Images in Markdown

Adding images could make your code documentation interesting and more visually appealing. It also helps to add supporting diagrams or images. Hyperlinks, as we know, help link text to links that could offer more details on that topic. Markdown allows you to include links and images in your documentation.

/// ## Links
/// [Java Documentation](https://docs.oracle.com/en/java/)
///
/// ## Images
/// ![Java Logo](https://www.oracle.com/a/tech/img/cb88-java-logo-001.jpg)
///
/// @param url The URL to process
/// @return A processed URL

Tables in Markdown

Arranging data and information in a tabular format helps us to compare and consume data in a better way. Markdown allows you to create tables in your documentation.

/// ## Basic Table
///
/// | Header 1 | Header 2 | Header 3 |
/// |----------|----------|----------|
/// | Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3 |
/// | Row 2, Col 1 | Row 2, Col 2 | Row 2, Col 3 |
/// | Row 3, Col 1 | Row 3, Col 2 | Row 3, Col 3 |
///
/// ## Alignment
///
/// | Left-aligned | Center-aligned | Right-aligned |
/// |:-------------|:-------------:|-------------:|
/// | Left | Center | Right |
/// | Left | Center | Right |
///
/// ## Complex Table
///
/// | Method | Description | Return Type | Throws |
/// |--------|-------------|-------------|--------|
/// | `get(Object key)` | Returns the value to which the specified key is mapped | `V` | `ClassCastException`, `NullPointerException` |
/// | `put(K key, V value)` | Associates the specified value with the specified key | `V` | `ClassCastException`, `NullPointerException`, `UnsupportedOperationException` |
/// | `remove(Object key)` | Removes the mapping for a key from this map if it is present | `V` | `UnsupportedOperationException`, `ClassCastException`, `NullPointerException` |
///
/// @param data The data to tabulate
/// @return A tabulated representation of the data

public String tablesExample(Map data) {
    return "Tabulated data";
}

Blockquotes in Markdown

Basic and nested blockquotes can appear in documentation comments. Here’s how you could include blockquotes in your documentation comments:

/// ## Basic Blockquote
/// > This is a blockquote.
/// >
/// > It can span multiple lines.
///
/// ## Nested Blockquotes
/// > This is the first level of quoting.
/// >
/// > > This is nested blockquote.
/// >
/// > Back to the first level.
///
/// ## Blockquotes with Other Elements
/// > #### Heading in a blockquote
/// >
/// > - List item in a blockquote
/// > - Another list item
/// >
/// > ```java
/// > // Code in a blockquote
/// > System.out.println("Hello, Markdown!");
/// > ```
///
/// @param quote The quote to process
/// @return A processed quote

public String blockquotesExample(String quote) {
    return "Processed quote: " + quote;
}

Please check out this link for more markdown markups.

Convert all existing HTML Javadoc comments to Markdown?

Just because you can, doesn’t imply you should.

Revisit the reasons why Markdown was added as an option to write JavaDoc comments – simplicity and readability. If folks using your libraries are facing issues with the Java comments that are written using the HTML tags (their tools doesn’t help much), convert them to Markdown using the ways shown above. You could also encourage others to use IntelliJ IDEA to have better rendering of the comments in their existing format. 

JDK’s Javadoc utility to generate documentation comments

You can use the javadoc tool shipped with the JDK to create elaborate documentations for your code base. The following gif shows how you could run this utility on the command prompt. For demo purposes, I’m using the following basic command to generate this documentation (creates documentation file structure in directory ‘doc’ for all the .java files. Feel free to check out the advance options:

javadoc -d docs *.java

Here’s the gif showing the docs folder that was generated on execution of the javadoc command. I can view the source code in my browser or choose to preview it from multiple options such as the Built-in preview in IntelliJ IDEA, or any of the web browsers installed on my system (I chose the later):

Interview with Jonathan Gibbons, Oracle, on Markdown Documentation Comments

We interviewed Jonathan Gibbons, Java SE Language Tools Team Lead at Oracle and owner of JEP 467, that is, Markdown Documentation Comments, and Dmitry Chuyko, Senior Architect at BellSoft and OpenJDK contributor in the ‘JEP Explained’ series. 

Jonathan started this interview by addressing what this feature is about and why it was added. On the face of it, a lot of developers would say that this is just Markdown. But Jonathan had other views. He shared why he thinks it’s not all down to Markdown’s quirks. Dmitry helped us understand the relevance of Javadoc documentation from the perspective of developers. He mentioned that developers often write Javadoc documentation to help their peers use codebases, libraries, and frameworks in the intended way. He also covered whether this feature should be relevant only to those developing libraries or APIs or to all developers in general.

Jonathan discussed the different variations of Markdown at length, detailing why the specific version is important and relevant. At the end, Jonathan covered the key considerations when converting between the HTML and Markdown documentation styles, with special attention paid to horizontal and vertical whitespaces and excessive HTML. 

Summary

If you want more developers to use your framework or libraries, you must include Documentation comments in your code. This blog post covers Markdown documentation comments in Java, a new feature in Java 23. Instead of the usual HTML-based Javadoc comments, you can now use Markdown that has a simpler syntax. These comments start with ///, instead of the regular /**.. */ used with the HTML Javadoc comments.

So why consider Markdown to write documentation comments? It’s widely used, beginner-friendly, and integrates well with existing tools. But don’t confuse these with regular multiline comments—Markdown documentation comments are specifically for generating Javadoc.

IntelliJ IDEA supports Markdown documentation comments with “Reader Mode” for better readability and offers inspection and context-action to convert old HTML-based Javadoc to Markdown. The post includes multiple examples, such as, how to use markdown to format headings, lists, code blocks, links, images, tables, and blockquotes.

It also covers how to use the javadoc tool to turn Markdown comments into HTML docs and gives practical advice on when it’s worth converting your existing Javadoc comments to Markdown. Happy commenting!