Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Using Markdown Syntax in Javadoc

DZone's Guide to

Using Markdown Syntax in Javadoc

· Java Zone ·
Free Resource

Verify, standardize, and correct the Big 4 + more– name, email, phone and global addresses – try our Data Quality APIs now at Melissa Developer Portal!

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.

Developers! Quickly and easily gain access to the tools and information you need! Explore, test and combine our data quality APIs at Melissa Developer Portal – home to tools that save time and boost revenue. Our APIs verify, standardize, and correct the Big 4 + more – name, email, phone and global addresses – to ensure accurate delivery, prevent blacklisting and identify risks in real-time.

Topics:

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}