Javadoc 注释中的多行代码示例 [英] Multiple line code example in Javadoc comment
问题描述
我有一个小代码示例,我想包含在方法的 Javadoc 注释中.
/*** -- 例如:遍历 Map 对象列表 --* <代码>* 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 查询 - 选择语句* @return 地图对象列表*/
问题是代码示例显示在 Javadoc 中,没有换行符,因此难以阅读.
-- 例如:循环遍历 Map 对象列表 -- 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"));}参数查询——选择语句返回:地图对象列表
我想我假设代码标签会处理换行符是错误的.在 Javadoc 注释中格式化代码示例的最佳方法是什么?
除了已经提到的
标签,你还应该使用@code
JavaDoc 注释,当涉及到 HTML 实体问题(尤其是泛型)时,这将使生活变得更轻松,例如:*
* {@代码* 设置<字符串>s;* System.out.println(s);* }* </pre>将给出正确的 HTML 输出:
Set
s;System.out.println(s); 虽然省略
@code
块(或使用标记)将导致 HTML 如下所示:
Set s;System.out.println(s);
作为参考,可以找到 Java SE 8 中可用的标记描述的完整列表 此处.
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, a full list of tag descriptions available in Java SE 8 can be found here.
这篇关于Javadoc 注释中的多行代码示例的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!