Translation: Using Markdown syntax in Javadoc comments

Using Markdown Syntax in Javadoc Comments

In this post, we'll look at how you can write Javadoc comments using Markdown instead of the standard Javadoc syntax. So what is Markdown? Markdown is a simple markup language that can optionally be translated into HTML using the tool of the same name. Markdown is widely used to format readme files, when writing forum posts, and in text editors to quickly create beautiful text documents. (Wikipedia: Markdown ) Text formatted in Markdown is very easy to read. Various flavors of Markdown are used on Stack Overflow or GitHub to format user-generated content.

Installation

By default, the Javadoc tool uses Javadoc comments to generate API documentation as HTML. This process can be reconfigured using Doclets . Doclets are Java programs that specify the content and formatting of the Javadoc tool's output file. Markdown-doclet replaces the standard Java Doclet and thus gives the developer the ability to use Markdown syntax in their Javadoc comments. You can install it in Maven using maven-javadoc-plugin. maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

Writing comments in Markdown

You can now use Markdown syntax to write 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 execution

mvn javadoc:Javadoc

the generated HTML API document is located at

target/site/apidocs.

The document generated for the above code looks like this: As you can see from the figure, Javadoc comments are perfectly converted to HTML.

Conclusion

Markdown has a clear advantage over standard Javadoc syntax: it is much easier to read in source code. Just take a look at some of the method comments in java.util.Map: many of them are full of formatting tags and are difficult to read without using additional tools. But you need to remember that Markdown can cause problems with tools and IDEs that can only work with standard Javadoc syntax. Source: Using Markdown syntax in Javadoc comments from our JCG partner Michael Scharhag from the mscharhag blog, Programming and Stuff.