1. Overview
1.概述
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.
在本教程中，我们将探索Javadoc注释的不同格式化方式。我们将重点分析写成文档注释的代码片段的格式。
2. Introduction
2.绪论
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.
Javadoc是一个为Java类生成文档的工具。它处理Java源文件中指定的文档注释，并生成一个相应的HTML页面。
Please refer to our article to know more about Javadoc documentation.
请参考我们的文章，了解更多关于Javadoc文档。
3. Code Snippets as Javadoc Comments
3.作为Javadoc注释的代码片段
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.
我们可以将代码片段作为一个Java类的文档注释的一部分。我们希望在生成的HTML页面上以正确的缩进和字符来查看这些代码片段。
Let’s try to add a Java code snippet as part of our comments:
让我们试着添加一个Java代码片断作为我们评论的一部分：
/**
* This is an example to show default behavior of code snippet formatting in Javadocs
*
* public class Application(){
*
* }
*
*/Corresponding HTML page:
相应的HTML页面。
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.
默认情况下，Javadoc注释中不保留换行和空格。这导致了不正确的缩进，特别是在多行代码片段的情况下。
Let’s find a way to maintain correct indentations in our comments.
让我们找到一种方法，在我们的评论中保持正确的缩进。。
3.1. Using the <pre> Tag
3.1.使用<pre>标签
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:
HTML提供了<pre>标签来表示预格式化的文本。它保留了所包围文本的空格和换行符，从而保留了代码片段所需的缩进：
/**
* 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:
相应的HTML页面。
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.
在这里，我们已经成功地保留了代码片段所需的空格和换行。不过，我们现在遇到了一个不同的问题。我们无法看到Generics 作为代码片段的一部分输入的。
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.
当评论被解析到HTML页面时，部分代码片段可能被误解为HTML标签，如上例中的<Integer>。
Let’s explore ways to keep correct formatting for HTML characters embedded within our comments.
让我们探讨如何保持嵌入我们评论中的HTML字符的正确格式。
3.2. Using HTML Character Entities
3.2.使用HTML Character 实体
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.
如果我们的代码片段包含HTML保留字符，如’<‘、’>‘或’&‘，在解析注释时，这些可以被解释为HTML字符。为了保留这些字符，我们可以使用Character实体来代替所需的字符。
For example, we can use < 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<Integer> nums = new ArrayList<>();
* }
*
* </pre>
*/Corresponding HTML page:
相应的HTML页面。
3.3. Using @code Tag
3.3.使用@code标签
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:
Javadoc提供了一个@code标签，该标签将嵌入括号内的注释视为源代码而非HTML字符。这使我们能够直接使用HTML保留字符，而不需要使用Character实体来转义：。
/**
* 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:
相应的HTML页面。
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.
请注意，@code标签并不能解决我们评论中涉及的缩进问题。为此，我们需要另外使用<pre>标签。
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.
正如我们在上面看到的，Javadoc使用’@‘字符来识别标签。如果我们的代码片段中有’@‘，就会被Javadoc误解，导致注释的不正确呈现。
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:
对应的HTML页面：。
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:
正如我们所看到的，Javadoc将@Getter作为一个标签来处理，注释并没有被正确呈现。我们可以在Javadoc提供的@code标签内嵌入注释（或使用@字符的代码）：
/**
* 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:
相应的HTML页面。
3.4. Using @literal Tag
3.4.使用@literal标签
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:
我们也可以通过使用@literal标签来实现类似的行为。@code标签和@literal标签的唯一区别是，@code标签以代码字体格式化所包围的文本：
/**
* 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:
相应的HTML页面。
Thus, we got our code snippets rendered correctly on the HTML page.
因此，我们得到了我们的代码片段在HTML页面上的正确呈现。。
3.5. Formatting jQuery Code Snippets
3.5.格式化jQuery代码片段
Here, we’ve taken an example of a Java code snippet. The same functionalities are applicable for any other language as well.
在这里，我们举了一个Java代码片段的例子。同样的功能也适用于任何其他语言。
Let’s include a simple jQuery code snippet as documentation comment:
让我们包括一个简单的jQuery代码片段作为文档注释：
/**
* 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:
相应的HTML页面。
3.6. Formatting HTML Code Snippets
3.6 格式化HTML代码片段
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.
到目前为止，我们已经意识到，一方面，Javadoc使我们能够使用HTML标签来格式化我们的评论，而另一方面，当我们想使用没有标记的HTML字符时，它也可能导致问题。
For example, we may want to insert HTML code snippets in our comments.
例如，我们可能想在评论中插入HTML代码片段。
Let’s insert an HTML code snippet as part of our documentation comment and see how it behaves:
让我们插入一个HTML代码片段作为我们的文档注释的一部分，看看它是如何表现的：
/**
* 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:
相应的HTML页面。
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:
在这里，我们可以看到，嵌入在评论中的代码片段已经被解析成一个带有HTML标记的HTML页面。我们可以使用@code标签来解决这个问题，就像上面讨论的那样：。
/**
* 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:
相应的HTML页面。
4. Conclusion
4.总结
We’ve explored different ways of formatting Javadoc comments. We can choose the formatting options as per our requirements to generate well-formatted documentation.
我们已经探索了Javadoc注释的不同格式化方式。我们可以根据自己的要求选择格式化选项，以生成格式良好的文档。
We can use HTML tags to enhance the formatting of Javadoc comments, as well as escape them whenever it suits our requirements.
我们可以使用HTML标签来加强Javadoc注释的格式化，也可以在符合我们要求的时候转义它们。