Add a Reference to Method Parameters in Javadoc – 在Javadoc中添加对方法参数的引用

最后修改: 2021年 9月 30日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

In the Java language, we can generate documentation in HTML format from Java source code using Javadoc. In this tutorial, we’ll learn about different ways to add a reference to method parameters in Javadoc.

在Java语言中，我们可以使用Javadoc从Java源代码生成HTML格式的文档。在本教程中，我们将学习在Javadoc中为方法参数添加引用的不同方法。

2. Different Ways to Add a Reference to a Method Parameter

2.为方法参数添加引用的不同方法

In this section, we’ll talk about adding a reference to a method parameter in Javadoc. We’ll see the usage of inline tag {@code} and HTML style tag </code> in Javadoc.

在本节中，我们将讨论在Javadoc中为方法参数添加一个引用。我们将看到Javadoc中内联标签{@code}和HTML风格标签</code> 的用法。

Further, we’ll see how {@code} and <code> tag take care of a few special cases:

此外，我们将看到 {@code}和<code>标签如何处理一些特殊情况。

  • displaying special characters ‘<‘, ‘>’, and ‘@’
  • indentation and line breaks
  • handling of escaping of HTML codes — for example, < which translates to symbol ‘<‘

2.1. The {@code} Tag

2.1.{@code}标签

{@code text} is an inline tag that was included in JDK 1.5.

{@code text}是一个内联标签，包含在JDK 1.5中。

The {@code} tag formats literal text in the code font. {@code abc} is equivalent to <code>{@literal abc}</code>.

{@code}标签用代码字体格式化字面文本。{@code abc}相当于<code>{@literal abc}</code>。

We don’t need to manually escape any special character used inside the {@code} tag.

我们不需要手动转义任何在{@code}标签内使用的特殊字符。。

When we use the {@code} tag, it:

当我们使用{@code}标签时，它。

  • displays ‘<‘ and ‘>’ correctly
  • displays ‘@’ correctly
  • does not need to escape special characters via HTML number codes
  • is more readable and concise

Let’s create a simple method in a class and add some Javadoc using the {@code} tag:

让我们在一个类中创建一个简单的方法，并使用{@code}标签添加一些Javadoc。

/**
  * This method takes a {@code String} 
  * and searches in the given list {@code List<String>}
  * 
  * @param name
  *        Name of the person
  * @param avengers
  *        list of Avengers names
  * @return true if found, false otherwise
  */
public Boolean isAvenger(String name, List<String> avengers) {
    return avengers.contains(name);
}

Here, we can see that we don’t need to escape the special characters ‘<‘ and ‘>’.

在这里，我们可以看到，我们不需要转义特殊字符'<‘和’>’。

The generated Javadoc will render the HTML output as:

生成的Javadoc将呈现为HTML输出。

 

Similarly, we can see that we don’t need to escape the ‘@’ character:

类似地，我们可以看到我们不需要转义’@’字符：。

/**
  * This is sample for showing @ use without any manual escape.
  * {@code @AnyAnnotaion}
  * 
  */
public void javadocTest() {
}

This will render to HTML Javadoc as:

这将在HTML Javadoc中呈现为。

 

In the case of a multiline code snippet in Javadoc, {@code} will not maintain the indentation and line break. To overcome this, we can use HTML tag <pre> along with {@code}. However, we need to escape the ‘@’ character in this case.

在Javadoc中的多行代码片段的情况下，{@code}不会保持缩进和换行。为了克服这个问题，我们可以使用HTML标签<pre>与{@code}一起。然而，在这种情况下，我们需要转义’@’字符。

2.2. The <code> Tag

2.2.<code>标签

<code> is an HTML style tag supported by Javadoc.

<code>是Javadoc支持的一个HTML样式标签。

When we use the <code> tag, it:

当我们使用<code>标签时，它。

  • doesn’t display ‘<‘ and ‘>’ correctly
  • requires to escape special characters via HTML number codes
  • is not so readable

Let’s consider the same example again. We can see that the generated Javadoc HTML is missing the <String> parameterized type after List in our paragraph:

让我们再考虑一下同一个例子。我们可以看到，生成的Javadoc HTML在我们的段落中<String> List之后缺少参数化的类型。

/**
  * This method takes a <code>String</code>
  * and searches in the given <code>List<String></code>
  * 
  * @param name
  *        Name of the person
  * @param avengers
  *        list of Avengers names
  * @return true if found, false otherwise
  */
public Boolean isAvenger(String name, List<String> avengers) {
    return avengers.contains(name);
}


Here, if we escape the special characters ‘<‘ and ‘>’ in our method comment, then it will render the correct <String> in Javadoc:


在这里，如果我们在方法注释中转义特殊字符'<‘和’>’，那么它将在Javadoc中呈现正确的<String>。

/**
  * This method takes a <code>String</code>
  * and searches in the given <code>List<String></code>
  * 
  * @param name
  *        Name of the person
  * @param avengers
  *        list of Avengers names
  * @return true if found, false otherwise
  */
public Boolean isAvenger(String name, List<String> avengers) {
    return avengers.contains(name);
}

 

3. Conclusion

3.总结

In this tutorial, we first talked about how to use {@code} and <code> to reference method parameters in Javadoc. Then we described the handling of special characters by these tags. In conclusion, we now understand how to add references to method parameters in Javadoc, and we can see that {@code} is better than <code> any day.

在本教程中，我们首先谈到了如何使用{@code}和<code>来引用Javadoc中的方法参数。然后我们描述了这些标签对特殊字符的处理。总之，我们现在明白了如何在Javadoc中添加对方法参数的引用，并且我们可以看到 {@code}比<code>更好。比<code>更好。