Javadoc注释中的多行代码示例

我有一个小的代码示例，我想在方法的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注释中格式化代码示例的最佳方法是什么？

#1楼

使用Java SE 1.6，看起来所有UPPERCASE 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>
 */

这将产生与常规代码完全相似的输出，并保留常规代码间距和换行符。

#2楼

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

Eg: List<MyClass> myObject = null; 显示为List myObject = null; 与firts和作为List<MyClass> myObject = null; 与第二

#3楼

在Javadoc注释中包含特定的代码示例时，我经历了一段非常艰难的时期。我想分享这个。
请注意以下事项：

旧<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();

#4楼

我可以使用代码1中显示的以下代码生成美观的HTML文件。

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

史蒂夫·B（Steve B）的建议（代码3）似乎给出了最好的结果，即使按了Alt + Shift + F，也仍然保持了预期的格式。

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

（代码3）

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

#5楼

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

使用JDK8更新

正确代码的最低要求是<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>周围会产生警告。

来源：oschina

链接：https://my.oschina.net/stackoom/blog/3158140

标签

netbeans

awt

java

JDK