Javadoc注释中的多行代码示例
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页面：
在这里，我们成功地保留了代码段所需的空格和换行符。但我们现在遇到了一个不同的问题：我们无法看到 泛型作为代码段的一部分输入。
当注释被解析成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页面：
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页面：
请注意@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进程 @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页面：
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页面：
因此，我们在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页面：
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页面：
在这里，我们可以看到嵌入在注释中的代码段已经 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页面：
4.结论
我们探索了格式化Javadoc注释的不同方法。 我们可以根据需要选择格式选项，以生成格式良好的文档。
我们可以使用HTML标记来增强Javadoc注释的格式，并在任何适合我们要求的时候转义它们。
- 本文标签： Java
- 本文链接： https://www.v8en.com/article/273
- 版权声明： 本文由SIMON原创发布，转载请遵循《署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)》许可协议授权
