Over a million developers have joined DZone.

Using Markdown Syntax in Javadoc

· Java Zone

Check out this 8-step guide to see how you can increase your productivity by skipping slow application redeploys and by implementing application profiling, as you code! Brought to you in partnership with ZeroTurnaround.

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.

Setup
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.

<build>
	<plugins>
		<plugin>
			<artifactId>maven-javadoc-plugin</artifactId>
			<version>2.9</version>
			<configuration>
				<doclet>ch.raffael.doclets.pegdown.PegdownDoclet</doclet>
				<docletArtifact>
					<groupId>ch.raffael.pegdown-doclet</groupId>
					<artifactId>pegdown-doclet</artifactId>
					<version>1.1</version>
				</docletArtifact>
				<useStandardDocletOptions>true</useStandardDocletOptions>
			</configuration>
		</plugin>
	</plugins>
</build>


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.


Conclusion
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.

The Java Zone is brought to you in partnership with ZeroTurnaround. Check out this 8-step guide to see how you can increase your productivity by skipping slow application redeploys and by implementing application profiling, as you code!

Topics:

Published at DZone with permission of Michael Scharhag, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}