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注释中设置代码示例的最佳方式是什么？
除了已经提到的<pre>标签之外，您还应该使用@code JavaDoc注释，这对于HTML实体问题（特别是对于generics）将使生活更加轻松，例如：
* <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);
（仅供参考，可以在这里findJava SE 8标签描述： Javadoc标签 ）
在javadoc评论中包含特定的代码示例，我感到非常难过。 我想分享这一个。
请注意以下事项：
- 使用旧的
<code>– 标签来防止大括号被解释 - 使用“new”
{@code ...}– tag来获得输出中包含的generics - 在
{@literal @}Override通过“{@literal @}Override”转义@符号，因为javadoc生成器在那里“倾斜”，因为@直接位于打开的大括号之后 - 移除
{@code和{@literal前面的一个空格，以补偿内部空间并保持alignment
javadoc代码：
/** this methods adds a specific translator from one type to another type. ` * ie * <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();
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></pre>标签括起你的多行代码。
您需要<pre></pre>标记作为换行符，而其中的{@code ... }才是generics。 但是不允许将大括号放在与<generic>标签相同的行上，因为这样所有东西都会再次显示在1行上。
显示在一行上：
* .. * <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; } }
/** * <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>或周围会产生警告。
我能够用下面的代码片段生成好看的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生成如图2所示的生成的javadoc HTML文件。
< pre> A-->B \ C-->D \ \ G E-->F
（图2）
史蒂夫·B的build议（代码3）似乎给出了最好的结果，并保持格式化如预期，即使按Alt + Shift + F。
*<p><blockquote><pre> * A-->B * \ * C-->D * \ \ * G E-->F * </pre></blockquote>
（代码3）
使用代码3产生如图1所示的相同的javadoc HTML输出。
在<blockquote><pre>...和<pre>{@code....之间有明显的区别。前者将省略generics中的types声明，但后者将保留它。
Eg: List<MyClass> myObject = null; 显示为List myObject = null; 与firts和List<MyClass> myObject = null; 与第二
如果你是Android开发者，你可以使用：
<pre class=”prettyprint”> TODO:your code. </pre>
用Java代码在Javadoc中打印出您的代码。
尝试用“pre”replace“code”。 HTML中的pre标记将文本标记为预格式化，并且所有换行符和空格都将与您input的内容完全相同。
我附上我的示例代码与<pre class="brush: java"></pre>标记，并使用SyntaxHighlighter发布的javadocs。 它不会伤害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> */
这产生的输出看起来完全像常规代码，常规代码间距和新行完好无损。
我只是在这里阅读了Javadoc 1.5的引用，只有带有<和>的代码必须包含在{@code ...} 。 这里有个简单的例子：
/** * Bla bla bla, for example: * * <pre> * void X() { * List{@code <String>} a = ...; * ... * } * </pre> * * @param ... * @return ... */ .... your code then goes here ...
