DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Please enter at least three characters to search
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

The software you build is only as secure as the code that powers it. Learn how malicious code creeps into your software supply chain.

Apache Cassandra combines the benefits of major NoSQL databases to support data management needs not covered by traditional RDBMS vendors.

Generative AI has transformed nearly every industry. How can you leverage GenAI to improve your productivity and efficiency?

Modernize your data layer. Learn how to design cloud-native database architectures to meet the evolving demands of AI and GenAI workloads.

Related

  • Formatting Strings in Java: String.format() Method
  • Open Source: A Pathway To Personal and Professional Growth
  • Enhancing Software Quality with Checkstyle and PMD: A Practical Guide
  • How to Become a Software Engineer Without a CS Degree: Essential Strategies for Success

Trending

  • Next-Gen IoT Performance Depends on Advanced Power Management ICs
  • Medallion Architecture: Why You Need It and How To Implement It With ClickHouse
  • Docker Model Runner: Streamlining AI Deployment for Developers
  • Four Essential Tips for Building a Robust REST API in Java
  1. DZone
  2. Coding
  3. Java
  4. Using Markdown Syntax in Javadoc

Using Markdown Syntax in Javadoc

By 
Michael Scharhag user avatar
Michael Scharhag
·
Jun. 23, 14 · Interview
Likes (1)
Comment
Save
Tweet
Share
15.4K Views

Join the DZone community and get the full member experience.

Join For Free

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.

Javadoc Syntax (programming languages) code style

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

Opinions expressed by DZone contributors are their own.

Related

  • Formatting Strings in Java: String.format() Method
  • Open Source: A Pathway To Personal and Professional Growth
  • Enhancing Software Quality with Checkstyle and PMD: A Practical Guide
  • How to Become a Software Engineer Without a CS Degree: Essential Strategies for Success

Partner Resources

×

Comments
Oops! Something Went Wrong

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends:

Likes
There are no likes...yet! 👀
Be the first to like this post!
It looks like you're not logged in.
Sign in to see who liked this post!