Javadoc评论中有多行代码示例 [英] Multiple line code example in Javadoc comment

问题描述

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

  / ** 
 *  - 例：循环映射对象列表 -  
 *< ;代码> 
 * 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查询 - 选择语句
 * @return Map对象列表
 * / 
  

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

   - 例如：循环映射对象列表 -  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（ 字））; } 
参数
查询 -   - 选择语句
返回：
地图对象列表
  

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

< pre> 标签，您还应该使用 @code JavaDoc注释，这对于HTML实体问题会让生活更轻松特别是泛型），例如：

  *< pre> 
 * {@code 
 * Set< String> S; 
 * System.out.println（s）; 
 *} 
 *< / pre> 
  

会给出正确的HTML输出：

 组<字符串> S; 
 System.out.println（s）; 
  

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

  Set s; 
 System.out.println（s）; （仅供参考，可以在这里找到Java SE 8标记描述： $ b $> //docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#CHDJGIJBrel =noreferrer> Javadoc Tags ）
 
I have a small code example I want to include in the Javadoc comment for a method.  
/**
 * -- 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.  
-- 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 ?
解决方案
In addition to the already mentioned <pre> tags, you should also use the @code JavaDoc annotation, which will make life much easier when it comes to HTML entities issues (in particular with Generics), e.g.:
* <pre>
* {@code
* Set<String> s;
* System.out.println(s);
* }
* </pre>
Will give correct HTML output:
Set<String> s;
System.out.println(s);
While omitting the @code block (or using a <code> tag) will result in HTML like this:
Set s;
System.out.println(s);
(For reference, Java SE 8 tag descriptions can be found here: Javadoc Tags)

                        
这篇关于Javadoc评论中有多行代码示例的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！