Home » Software Development » Using Markdown syntax in Javadoc comments

About Michael Scharhag

Michael Scharhag
Michael Scharhag is a Java Developer, Blogger and technology enthusiast. Particularly interested in Java related technologies including Java EE, Spring, Groovy and Grails.

Using Markdown syntax in Javadoc comments

In this post we will see how we can write Javadoc comments using Markdown instead of the typical Javadoc syntax.

So what is Markdown?

Markdown is a plain text formatting syntax designed so that it optionally can be converted to HTML using a tool by the same name. Markdown is popularly used to format readme files, for writing messages in online discussion forums or in text editors for the quick creation of rich text documents.
(Wikipedia: Markdown)

Markdown is a very easy to read formatting syntax. Different variations of Markdown can be used on Stack Overflow or GitHub to format user generated content.


By default the Javadoc tool uses Javadoc comments to generate API documentation in HTML form. This process can be customized used
Doclets. Doclets are Java programs that specify the content and format of the output of the Javadoc tool.

The markdown-doclet is a replacement for the standard Java Doclet which gives developers the option to use Markdown syntax in their Javadoc comments. We can set up this doclet in Maven using the maven-javadoc-plugin.


Writing comments in Markdown

Now we can use Markdown syntax in Javadoc comments:

 * ## Large headline
 * ### Smaller headline
 * This is a comment that contains `code` parts.
 * Code blocks:
 * ```java
 * int foo = 42;
 * System.out.println(foo);
 * ```
 * Quote blocks:
 * > This is a block quote
 * lists:
 *  - first item
 *  - second item
 *  - third item
 * This is a text that contains an [external link][link].
 * [link]: http://external-link.com/
 * @param id the user id
 * @return the user object with the passed `id` or `null` if no user with this `id` is found
public User findUser(long id) {

After running mvn javadoc:javadoc we can find the generated HTML API documentation in target/site/apidocs.

The generated documentation for the method shown above looks like this:


As we can see the Javadoc comments get nicely converted to HTML.


Markdown has the clear advantage over standard Javadoc syntax that the source it is far easier to read. Just have a look at some of the method comments of java.util.Map. Many Javadoc comments are full with formatting tags and are barely readable without any tool. But be aware that Markdown can cause problems with tools and IDEs that expect standard Javadoc syntax.

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

and many more ....


Leave a Reply

Your email address will not be published. Required fields are marked *


Want to take your Java Skills to the next level?
Grab our programming books for FREE!
  • Save time by leveraging our field-tested solutions to common problems.
  • The books cover a wide range of topics, from JPA and JUnit, to JMeter and Android.
  • Each book comes as a standalone guide (with source code provided), so that you use it as reference.
Last Step ...

Where should we send the free eBooks?

Good Work!
To download the books, please verify your email address by following the instructions found on the email we just sent you.