Javadoc注释中的多行代码示例

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

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

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>
...

除了前面提到的<pre>标签，你还应该使用@code JavaDoc注释，这将使HTML实体问题(特别是泛型)变得更容易，例如:

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

将给出正确的HTML输出:

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

而省略@code块(或使用<code>标签)将导致这样的HTML:

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

作为参考，Java SE 8中可用的标记描述的完整列表可以在在这里中找到。

换行符需要使用<pre></pre>标记，泛型需要使用换行符内部的{@code ... }标记。但是不允许将开始大括号与<generic>标记放在同一行上，因为这样所有内容将再次显示在一行上。

显示在一行上:

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

显示带有换行符:

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

另一件奇怪的事情是，当你粘贴{@code的右括号时，它会显示:

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

输出:

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

我在示例代码中附上了<pre class="brush: java"></pre>标记，并对已发布的javadocs使用SyntaxHighlighter。它不会损害IDE，并使已发布的代码示例更漂亮。

使用Java SE 1.6，看起来所有大写的PRE标识符都是在Javadoc中做到这一点的最佳方式:

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

是最简单的方法。

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

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

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

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

javadoc代码:

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

被打印为

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

我能够用下面的代码片段生成好看的HTML文件——代码1中显示了它。

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

(代码1)

如图1所示，代码1变成了生成的javadoc HTML页面。

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

(图1)

然而，在NetBeans 7.2中，如果你按Alt+Shift+F(重新格式化当前文件)，代码1就会变成代码2。

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

(代码2)

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

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

(图2)

Steve B的建议(代码3)似乎给出了最好的结果，即使在按Alt+Shift+F后仍然保持格式化。

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

(3)代码

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

/**
* <blockquote><pre>
* {@code
* public Foo(final Class<?> klass) {
*     super();
*     this.klass = klass;
* }
* }
* </pre></blockquote>
**/

• <pre/>用于保存行。
• {@code必须有自己的行
• <blockquote/>只是用于缩进。

public Foo(final Class<?> klass) {
super();
this.klass = klass;
}

正确代码的最低要求是<pre/>和{@code}。

/**
* test.
*
* <pre>{@code
* <T> void test(Class<? super T> type) {
*     System.out.printf("hello, world\n");
* }
* }</pre>
*/

收益率

 <T> void test(Class<? super T> type) {
System.out.printf("hello, world\n");
}

可选的<blockquote/>插入缩进。

/**
* test.
*
* <blockquote><pre>{@code
* <T> void test(Class<? super T> type) {
*     System.out.printf("hello, world\n");
* }
* }</pre></blockquote>
*/

收益率

     <T> void test(Class<? super T> type) {
System.out.printf("hello, world\n");
}

插入<p>或用<p>和</p>包围会产生警告。

如果你是Android开发者，你可以使用:

<pre class=”prettyprint”>


TODO:your code.


</pre>

用Java代码在Javadoc中漂亮地打印代码。

我刚刚阅读了Javadoc 1.5参考在这里，只有代码与# eyz0和>必须封闭在{@code ...}。这里有一个简单的例子:

 /**
* Bla bla bla, for example:
*
* <pre>
* void X() {
*    List{@code <String>} a = ...;
*    ...
* }
* </pre>
*
* @param ...
* @return ...
*/
.... your code then goes here ...

这是我的意见。

正如其他答案所述，您应该将# EYZ0 # EYZ1与# EYZ2 # EYZ3结合使用。

使用pre和{@code}

• 将你的代码包装在<pre>和</pre>中可以防止你的代码崩溃成一行;
• 将代码包装在{@code }中，可以防止<， >和中间的所有内容消失。当代码包含泛型或lambda表达式时，这尤其有用。

注释的问题

当代码块包含注释时，就会出现问题。这可能是因为当@符号出现在Javadoc行的开头时，它被认为是一个类似于@param或@return的Javadoc标记。例如，这段代码可能被错误地解析:

/**
* Example usage:
*
* <pre>{@code
* @Override
* public void someOverriddenMethod() {

以上代码将完全消失在我的情况下。

为了解决这个问题，行不能以@开头:

/**
* Example usage:
*
* <pre>{@code  @Override
* public int someMethod() {
*     return 13 + 37;
* }
* }</pre>
*/

注意，在@code和@Override之间有两个空格，以保持与下一行对齐。在我的例子中(使用Apache Netbeans)，它被正确呈现。

至少在Visual Studio Code中，你可以通过将Javadoc注释包装成三反引号来强制它遵守换行符，如下所示:

/** ```markdown
* This content is rendered in (partial) markdown.
*
* For example, *italic* and **bold** text works, but [links](https://www.google.com) do not.
* Bonus: it keeps single line-breaks, as seen between this line and the previous.
``` */

我使用这两种方法没有任何问题:

<pre>
<code>
... java code, even including annotations
</code>
</pre>

而且

<pre class="code">
... java code, even including annotations
</pre>

当然，后者更简单，请观察class="code"部分

另外两种解决方案的结合似乎是完美的:

* <pre>{@code
*     {@literal @}Override
*     public void someMethod() {
*         Set<String> s;
*     }
* }</pre>

ie。使用<pre>{@code开始，使用}</pre>结束代码段。同样，将@替换为{@literal @}。

还没有找到更简单的解决办法。对于一门已经活跃开发了几十年的语言来说，这是相当可悲的。

从Java 18 (中413)开始，你可以使用@snippet标签:

/**
* -- ex: looping through List of Map objects --
* {@snippet :
* 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"));
* }
* }
*
* @param query - select statement
* @return List of Map objects
*/