Partner – Moderne – NPI EA (cat=Spring Boot)
announcement - icon

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Course – Black Friday 2026 – NPI EA – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

1. Overview

In this tutorial, we’ll explore different ways of formatting Javadoc comments. We’ll focus on analyzing the formatting of code snippets written as documentation comments.

2. Introduction

Javadoc is a tool for generating documentation for a Java class. It processes the documentation comments specified in a Java source file and generates a corresponding HTML page. 

Please refer to our article to know more about Javadoc documentation.

3. Code Snippets as Javadoc Comments

We can include code snippets as part of documentation comments for a Java class. We want to view the code snippets with correct indentation and characters on the generated HTML page.

Let’s try to add a Java code snippet as part of our comments:

/**
* This is an example to show default behavior of code snippet formatting in Javadocs
* 
* public class Application(){
* 
* }
* 
*/

Corresponding HTML page:

Javadoc Default

By default, line breaks and spaces aren’t preserved in the Javadoc comments. This results in improper indentation, especially in the case of multiline code snippets.

Let’s find a way to maintain correct indentations in our comments.

3.1. Using the <pre> Tag

HTML provides the <pre> tag to indicate preformatted text. It preserves the spaces and line breaks of the enclosed text, thereby preserving the required indentation for code snippets:

/**
* This is an example to show usage of HTML pre tag while code snippet formatting in Javadocs
* 
* <pre>
* public class Application(){
*     List<Integer> nums = new ArrayList<>();
* }
* 
* </pre>
*/

Corresponding HTML page:

Javadoc PRE

Here, we’ve successfully preserved the spaces and line breaks required for our code snippets. We’ve encountered a different problem now, though: We aren’t able to see the Generics entered as part of the code snippet.

As comments are parsed into an HTML page, parts of the code snippets can be misinterpreted as HTML tags, like <Integer> in the above example.

Let’s explore ways to keep correct formatting for HTML characters embedded within our comments.

3.2. Using HTML Character Entities

If our code snippet contains HTML reserved characters like ‘<’, ‘>’ or ‘&’, these can be interpreted as HTML characters while parsing the comments. To preserve these characters, we can use Character entities in place of the required characters.

For example, we can use &lt; to denote ‘<’ character:

/**
* This is an example to show usage of HTML character entities while code snippet formatting in Javadocs
* 
* <pre>
* public class Application(){
*     List&lt;Integer&gt; nums = new ArrayList<>();
* }
* 
* </pre>
*/

Corresponding HTML page:

Javadoc CharacterEntities

3.3. Using @code Tag

Javadoc provides a @code tag, which treats the comments embedded within brackets as source code instead of HTML characters. This enables us to use HTML reserved characters directly without escaping them using Character entities:

/**
* This is an example to show usage of javadoc code tag while code snippet formatting in Javadocs
* 
* <pre>
* 
* public class Application(){
*     {@code List<Integer> nums = new ArrayList<>(); }
* }
*
* </pre>
*/

Corresponding HTML page:

Javadoc Code Tag

Please note that the @code tag doesn’t address the indentation issues involved in our comments. For this, we need to use the <pre> tag additionally.

As we’ve seen above, Javadoc identifies the tags using ‘@’ characters. If we have ‘@’ as part of our code snippets, it’ll be misinterpreted by Javadoc, leading to the incorrect rendering of comments.

Let’s see this using an example:

/**
* This is an example to show issue faced while using annotations in Javadocs
* 
* <pre>
* 
* public class Application(){
*            @Getter
*     {@code List<Integer> nums = new ArrayList<>(); }
* }
*
* </pre>
*/

Corresponding HTML page:

Javadoc Annotation Issue

 

As we can see, Javadoc processes @Getter as a tag and comments aren’t rendered correctly. We can embed the annotations (or code using @ characters) within the @code tag provided by Javadoc:

/**
* This is an example to show usage of javadoc code tag for handling '@' character
* 
* <pre>
* 
* public class Application(){
*     {@code @Getter}
*     {@code List<Integer> nums = new ArrayList<>(); }
* }
*
* </pre>
*/

Corresponding HTML page:

Javadoc Annotations Code Tag

3.4. Using @literal Tag

We can achieve similar behavior by using the @literal tag as well. The only difference between the @code tag and @literal tag is that the @code tag formats the enclosed text in code font:

/**
* This is an example to show difference in javadoc literal and code tag
* 
* <p>
* 
* {@literal @Getter}
* {@literal List<Integer> nums = new ArrayList<>(); }
*   
* <br />
* {@code @Getter}
* {@code List<Integer> nums = new ArrayList<>(); }
* </p>
*/

Corresponding HTML page:

Javadoc Literal Vs Code Tag

Thus, we got our code snippets rendered correctly on the HTML page.

3.5. Formatting jQuery Code Snippets

Here, we’ve taken an example of a Java code snippet. The same functionalities are applicable for any other language as well.

Let’s include a simple jQuery code snippet as documentation comment:

/**
* This is an example to illustrate a basic jQuery code snippet embedded in documentation comments
* <pre>
* {@code <script>}
* $document.ready(function(){
*     console.log("Hello World!);
* })
* {@code </script>}
* </pre>
*/

Corresponding HTML page:

Javadoc jQuery Code

3.6. Formatting HTML Code Snippets

So far, we’ve realized that on one hand, Javadoc enables us to use HTML tags for formatting our comments, while on the other hand, it can also lead to issues when we want to use HTML characters without markup.

For example, we may want to insert HTML code snippets in our comments.

Let’s insert an HTML code snippet as part of our documentation comment and see how it behaves:

/**
* This is an example to illustrate an HTML code snippet embedded in documentation comments
* <pre>
* <html>
* <body>
* <h1>Hello World!</h1>
* </body>
* </html>
* </pre>
* 
*/

Corresponding HTML page:

Javadoc HTML Code Snippet

Here, we can see that the code snippet embedded within comments has been parsed into an HTML page with HTML markup. We can fix the issue using the @code tag as discussed above:

/**
* This is an example to illustrate an HTML code snippet embedded in documentation comments
* <pre>{@code
* <html>
* <body>
* <h1>Hello World!</h1>
* </body>
* </html>}
* </pre>
* 
*/

Corresponding HTML page:

Javadoc HTML Code Snippet Fixed

4. Conclusion

We’ve explored different ways of formatting Javadoc comments. We can choose the formatting options as per our requirements to generate well-formatted documentation.

We can use HTML tags to enhance the formatting of Javadoc comments, as well as escape them whenever it suits our requirements.

Partner – Moderne – NPI EA (tag=Refactoring)
announcement - icon

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.

Course – Black Friday 2026 – NPI EA – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW