mscharhag, Programming and Stuff;

A blog about programming and software development topics, mostly focused on Java technologies including Java EE, Spring and Grails.

Sunday, 22 June, 2014

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]:
 * @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:

Generated Javadoc screenshot

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.

You can find the source of this example project on GitHub.


  • Diego Magalhães - Monday, 23 June, 2014

    Nicely done, how does the markup shows up in the IDE?

  • Michael Scharhag - Friday, 27 June, 2014

    Hi Diego,

    i can only talk about IDEA. It shows the markup with the standard javadoc syntax highlighting. Words like @param or @return are highlighted. The rest of the markup is unaffected.

    A problem with IDEA is the quick documentation feature (ctrl-q). Here IDEA parses the javadoc comment and displays the result in a small popup. Unfortunately markdown syntax isn't propertly displayed here.

  • mike C - Friday, 27 June, 2014

    whether there is integration with pygments?

  • James Nelson - Saturday, 19 March, 2016

    Actually, Michael, if you go to the github for the project, it includes an explanation for installing it into intellij as well.

  • mchlfchr - Sunday, 18 September, 2016

    Has somebody brought into experience, if there is an Eclipse integration or plugin for tooltip/quick documentation usage?

Leave a reply