Javadoc 注释中的多行代码示例

Multiple line code example in Javadoc comment

提问by Mark

I have a small code example I want to include in the Javadoc comment for a method.

我有一个小代码示例，我想包含在方法的 Javadoc 注释中。

/**
 * -- ex: looping through List of Map objects --
 * <code>
 * for (int i = 0; i < list.size(); i++) {
 *      Map map = (Map)list.get(i);
 *      System.out.println(map.get("wordID"));
 *      System.out.println(map.get("word"));
 * }
 * </code>
 * 
 * @param query - select statement
 * @return List of Map objects
 */

The problem is the code example shows up in the Javadoc with no line breaks making it hard to read.

问题是代码示例显示在 Javadoc 中，没有换行符，因此难以阅读。

-- ex: looping through List of Map objects -- for (int i = 0; i list.size(); i++) { Map map = (Map)list.get(i); System.out.println(map.get("wordID")); System.out.println(map.get("word")); } 
Parameters
query - - select statement 
Returns:
List of Map objects 

I guess I am wrong in assuming the code tag would handle line breaks. What is the best way to format code examples in Javadoc comments ?

我想我假设代码标签会处理换行符是错误的。在 Javadoc 注释中格式化代码示例的最佳方法是什么？

采纳答案by Fabian Steeg

In addition to the already mentioned <pre>tags, you should also use the @codeJavaDoc annotation, which will make life much easier when it comes to HTML entities issues (in particular with Generics), e.g.:

除了已经提到的<pre>标签之外，您还应该使用@codeJavaDoc 注释，这将使处理 HTML 实体问题（尤其是泛型）时的生活变得更加轻松，例如：

* <pre>
* {@code
* Set<String> s;
* System.out.println(s);
* }
* </pre>

Will give correct HTML output:

将给出正确的 HTML 输出：

Set<String> s;
System.out.println(s);

While omitting the @codeblock (or using a <code>tag) will result in HTML like this:

省略@code块（或使用<code>标记）将导致 HTML 如下：

Set s;
System.out.println(s);

(For reference, Java SE 8 tag descriptions can be found here: Javadoc Tags)

（作为参考，可以在此处找到 Java SE 8 标签说明：Javadoc 标签）

回答by Zach Scrivena

Enclose your multiline code with <pre></pre>tags.

用<pre></pre>标签将多行代码括起来。

回答by Edwin

Try replacing "code" with "pre". The pre tag in HTML marks the text as preformatted and all linefeeds and spaces will appear exactly as you type them.

尝试用“pre”替换“code”。HTML 中的 pre 标记将文本标记为预格式化，所有换行符和空格都将在您键入时完全显示。

回答by Steve B.

The java source has lots of good examples for this. Here's an example from the head of "String.java":

java 源代码有很多很好的例子。这是“String.java”头部的一个例子：

....
 * is equivalent to:
 * <p><blockquote><pre>
 *     char data[] = {'a', 'b', 'c'};
 *     String str = new String(data);
 * </pre></blockquote><p>
 * Here are some more examples of how strings can be used:
 * <p><blockquote><pre>
 *     System.out.println("abc");
 *     String cde = "cde";
 *     System.out.println("abc" + cde);
 *     String c = "abc".substring(2,3);
 *     String d = cde.substring(1, 2);
 * </pre></blockquote>
...

回答by Rule

You need the <pre></pre>tags for the line breaks, and the {@code ... }inside them for generics. But then it's not allowed to place the opening brace on the same line as the <generic>tag, because then everything will be displayed on 1 line again.

您需要<pre></pre>换行符的标签，以及{@code ... }泛型的内部标签。但是不允许将左大括号与<generic>标签放在同一行，因为那样一切都会再次显示在 1 行上。

Displays on one line:

一行显示：

* ..
* <pre>
* {@code
* public List<Object> getObjects() {
*    return objects;
* }
* </pre>
* ..

Displays with line breaks:

显示换行符：

* ..
* <pre>
* {@code
* public List<Object> getObjects() 
* {
*    return objects;
* }
* </pre>
* ..

Another weird thing is when you paste the closing brace of {@code, it gets displayed:

另一个奇怪的事情是，当您粘贴 的右大括号时{@code，它会显示：

* ..
* <pre>
* {@code
*   public List<Object> getObjects() 
*   {
*     return objects;
*   }
* }
* </pre>
* ..

Output:

输出：

public List<Object> getObjects() 
{
   return objects;
}
}

回答by Jarek Przygódzki

I enclose my example code with <pre class="brush: java"></pre>tags and use SyntaxHighlighterfor published javadocs. It doesn't hurt IDE and makes published code examples beautiful.

我用<pre class="brush: java"></pre>标签附上了我的示例代码，并使用SyntaxHighlighter来发布 javadoc。它不会损害 IDE，并使发布的代码示例美观。

回答by Eugene_CD-adapco

Using Java SE 1.6, it looks like all UPPERCASE PRE identifiers is the best way to do this in Javadoc:

使用 Java SE 1.6，看起来所有大写 PRE 标识符是在 Javadoc 中执行此操作的最佳方法：

/**
 * <PRE>
 * insert code as you would anywhere else
 * </PRE>
 */

is the simplest way to do this.

是最简单的方法。

An Example from a javadoc I got from a java.awt.Event method:

我从 java.awt.Event 方法获得的 javadoc 中的一个示例：

/**
 * <PRE>
 *    int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
 *    int offmask = CTRL_DOWN_MASK;
 *    if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
 *        ...
 *    }
 * </PRE>
 */

This produces output that looks exactly like the regular code, with the regular code spacings and new lines intact.

这会产生与常规代码完全相同的输出，常规代码间距和新行保持不变。

回答by Tamas

There is a significant difference between <blockquote><pre>...and <pre>{@code....The former will omit the type declarations in generics but the latter will keep it.

<blockquote><pre>...和之间有一个显着的区别，<pre>{@code....前者会省略泛型中的类型声明，但后者会保留它。

E.g.: List<MyClass> myObject = null;displays as List myObject = null;with the firts and as List<MyClass> myObject = null;with the second

E.g.: List<MyClass> myObject = null;显示为List myObject = null;与firts并作为List<MyClass> myObject = null;与所述第二

回答by Christoph Naber

I had a really tough time with including a specific code example in a javadoc comment. I'd like to share this one.
Please note the following:

我在 javadoc 注释中包含一个特定的代码示例时遇到了非常困难的时间。我想分享这个。
请注意以下事项：

• usage of old <code>- tag to prevent the curly brackets from being interpreted
• usage of "new" {@code ...}- tag to get the generics included in the output
• escaping of the @ sign in @Overridevia "{@literal @}Override" because javadoc generator "tilts" there due to the fact that the @ goes directly after an opening curly bracket
• remove one space in front of {@codeand {@literal, to compensate inner spaces and keep the alignment

• 使用 old <code>- 标签防止大括号被解释
• 使用“new” {@code ...}- 标记以获取输出中包含的泛型
• @Override通过 " {@literal @}Override"转义 @ 登录，因为 javadoc 生成器在那里“倾斜”，因为 @ 直接在左大括号之后
• 删除{@code和前面的一个空格{@literal，以补偿内部空间并保持对齐

javadoc code:

文档代码：

/** this methods adds a specific translator from one type to another type. `
  * i.e.
  * <pre>
  * <code>new BeanTranslator.Builder()
  *   .translate(
  *     new{@code Translator<String, Integer>}(String.class, Integer.class){
  *      {@literal @}Override
  *       public Integer translate(String instance) {
  *         return Integer.valueOf(instance);
  *       }})
  *   .build();
  * </code>
  * </pre>
  * @param translator
  */

gets printed as

被打印为

new BeanTranslator.Builder()
  .translate(
    new Translator<String, Integer>(String.class, Integer.class){
      @Override
      public Integer translate(String instance) {
        return Integer.valueOf(instance);
      }})
  .build();

回答by bitsdanceforme

I was able to generate good looking HTML files with the following snip-it shown in Code 1.

我能够使用代码 1 中显示的以下 snip-it 生成漂亮的 HTML 文件。

 * <pre>
 * {@code
 * A-->B
 *  \
 *   C-->D
 *    \   \
 *     G   E-->F
 * }
 *</pre>

(Code 1)

（代码 1）

Code 1 turned into the generated javadoc HTML page in Fig 1, as expected.

正如预期的那样，代码 1 变成了图 1 中生成的 javadoc HTML 页面。

A-->B
 \
  C-->D
   \   \
    G   E-->F

(Fig. 1)

（图。1）

However, in NetBeans 7.2, if you hit Alt+Shift+F (to reformat the current file), Code 1 turns in to Code 2.

但是，在 NetBeans 7.2 中，如果您按 Alt+Shift+F（重新格式化当前文件），代码 1 会变成代码 2。

 * <
 * pre>
 * {@code
 * A-->B
 *  \
 *   C-->D
 *    \   \
 *     G   E-->F
 * }
 * </pre>

(Code 2)

（代码 2）

where the first <pre>is now broken onto two lines. Code 2 produces generated javadoc HTML file as shown in Fig 2.

第一个<pre>现在被分成两行。代码 2 生成生成的 javadoc HTML 文件，如图 2 所示。

< pre> A-->B \ C-->D \ \ G E-->F

(Fig 2)

(图2)

Steve B's suggestion (Code 3) seems to give the best results and remains formatted as expected even after hitting Alt+Shift+F.

Steve B 的建议（代码 3）似乎给出了最好的结果，并且即使在按下 Alt+Shift+F 后仍保持按预期格式化。

*<p><blockquote><pre>         
* A-->B
*  \
*   C-->D
*    \   \
*     G   E-->F
* </pre></blockquote>

(Code 3)

（代码 3）

Use of Code 3 produces the same javadoc HTML output as shown in Fig 1.

使用代码 3 产生与图 1 相同的 javadoc HTML 输出。