我有一个小代码示例,我想在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
 */

问题是在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 

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


当前回答

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

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

ie。使用<pre>{@code开始和}</pre>结束片段。同样,用{@literal @}替换@。

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

其他回答

<blockquote><pre>…以前和< > {@code……前者将省略泛型中的类型声明,而后者将保留它。

例如: List<MyClass> myObject = null; List myObject = null;List<MyClass> myObject = null;第二种情况

从Java 18 (JEP 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
 */

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

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

<pre class=”prettyprint”>

TODO:your code.

</pre>

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

我能够用下面的代码片段生成好看的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输出。