原创

Javadoc注释中的多行代码示例

温馨提示:
本文最后更新于 2022年11月15日,已超过 21 天没有更新。若文章内的图片失效(无法正常加载),请留言反馈或直接联系我

1.概述

在本教程中,我们将探索格式化Javadoc注释的不同方法。我们将 重点分析代码段的格式 写为文档注释。

2.简介

Javadoc是一个为Java类生成文档的工具。它 处理Java源文件中指定的文档注释,并生成相应的HTML页面.

请参阅我们的文章了解更多 Javadoc文档.

3.代码段作为Javadoc注释

我们可以将代码片段作为Java类的文档注释的一部分。我们希望在生成的HTML页面上查看具有正确缩进和字符的代码段。

让我们尝试添加一个Java代码片段作为注释的一部分:

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

对应的HTML页面:

默认情况下,Javadoc注释中不保留换行符和空格这会导致不正确的缩进,尤其是在多行代码段的情况下。

让我们在评论中找到一种保持正确缩进的方法。

3.1.使用<pre>标签

HTML提供了标记以指示预格式化文本。 它保留了所附文本的空格和换行符,从而保留代码段所需的缩进:

/**
* 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>
*/

对应的HTML页面:

Javadoc PRE

在这里,我们成功地保留了代码段所需的空格和换行符。但我们现在遇到了一个不同的问题:我们无法看到 泛型作为代码段的一部分输入。

当注释被解析成HTML页面时,部分代码段可能被误解为HTML标记喜欢 在上述示例中。

让我们探索如何保持嵌入注释中的HTML字符的正确格式。

3.2.使用HTML 性格 实体

如果我们的代码段包含HTML保留字符,如“<', '>'或'&',解析注释时,这些字符可以解释为HTML字符。为了保留这些字符,我们可以使用 性格 实体 代替所需的字符。

例如,我们可以使用<;表示'<'字符:

/**
* 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>
*/

对应的HTML页面:

Javadoc CharacterEntities

3.3.使用 @code 标签

Javadoc提供了@code 标签,其中 将括号中嵌入的注释视为源代码而不是HTML字符。这使我们能够直接使用HTML保留字符,而无需使用 性格 实体:

/**
* 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>
*/

对应的HTML页面:

Javadoc Code Tag

请注意@code 标记不能解决缩进问题 参与我们的评论。为此,我们需要使用<pre>标签

如上所述, Javadoc使用'@'个字符。如果我们有@“作为我们代码片段的一部分,它会被Javadoc误解,导致注释的错误呈现。

让我们用一个例子来看看:

/**
* 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>
*/

对应的HTML页面:

Javadoc Annotation Issue

如我们所见,Javadoc进程 @Getter 因为标签和注释没有正确呈现。我们可以 使用嵌入注释(或代码 @character@code 标签 由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>
*/

对应的HTML页面:

Javadoc Annotations Code Tag

3.4.使用 @literal 标签

我们可以实现 通过使用@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>
*/

对应的HTML页面:

Javadoc Literal Vs Code Tag

因此,我们在HTML页面上正确地呈现了代码片段。

3.5.格式化jQuery代码段

这里,我们举了一个Java代码片段的例子。同样的功能也适用于任何其他语言。

让我们将一个简单的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>
*/

对应的HTML页面:

Javadoc jQuery Code

3.6.格式化HTML代码段

到目前为止,我们已经意识到,一方面,Javadoc使我们能够使用HTML标记来格式化我们的评论,另一方面,当我们想使用没有标记的HTML字符时,它也会导致问题。

例如,我们可能希望在注释中插入HTML代码段。

让我们在文档注释中插入一个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>
* 
*/

对应的HTML页面:

Javadoc HTML Code Snippet

在这里,我们可以看到嵌入在注释中的代码段已经 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>
* 
*/

对应的HTML页面:

Javadoc HTML Code Snippet Fixed

4.结论

我们探索了格式化Javadoc注释的不同方法。 我们可以根据需要选择格式选项,以生成格式良好的文档。

我们可以使用HTML标记来增强Javadoc注释的格式,并在任何适合我们要求的时候转义它们。

正文到此结束