[英]Multiple line code example in Javadoc comment
我有一個小代碼示例,我想包含在方法的 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 實體問題(尤其是泛型)時的工作變得更加輕松,例如:
* <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);
作為參考,可以在此處找到 Java SE 8 中可用的標記描述的完整列表。
我在 javadoc 注釋中包含一個特定的代碼示例時遇到了非常困難的時間。 我想分享這個。
請注意以下事項:
<code>
用法 - 防止大括號被解釋的標簽{@code ...}
- 標記以獲取輸出中包含的泛型@Override
通過“ {@literal @}Override
”,因為javadoc的發電機“傾斜”有由於該@中的開口大括號之后直接進入的事實{@code
和{@literal
前面的一個空格,以補償內部空格並保持對齊文檔代碼:
/** 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();
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 ... }
用於泛型。 但是不允許將左大括號與<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;
}
正確代碼的最低要求是<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>
包圍會產生警告。
我能夠使用代碼 1 中顯示的以下 snip-it 生成漂亮的 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)
Steve B 的建議(代碼 3)似乎給出了最好的結果,並且即使在按下 Alt+Shift+F 后仍保持按預期格式化。
*<p><blockquote><pre>
* A-->B
* \
* C-->D
* \ \
* G E-->F
* </pre></blockquote>
(代碼 3)
使用代碼 3 產生與圖 1 相同的 javadoc HTML 輸出。
這是我的兩分錢。
正如其他答案已經指出的那樣,您應該將<pre>
</pre>
與{@code
}
結合使用。
pre
和{@code}
<pre>
和</pre>
可防止您的代碼折疊到一行;{@code
}
可以防止<
、 >
以及它們之間的所有內容消失。 當您的代碼包含泛型或 lambda 表達式時,這尤其有用。注釋問題
當您的代碼塊包含注釋時可能會出現問題。 這可能是因為當@
符號出現在 Javadoc 行的開頭時,它被認為是一個 Javadoc 標記,如@param
或@return
。 例如,此代碼可能會被錯誤解析:
/**
* Example usage:
*
* <pre>{@code
* @Override
* public void someOverriddenMethod() {
在我的情況下,上面的代碼將完全消失。
要解決此問題,該行不得以@
符號開頭:
/**
* Example usage:
*
* <pre>{@code @Override
* public int someMethod() {
* return 13 + 37;
* }
* }</pre>
*/
請注意, @Override
@code
和@Override
之間有兩個空格,以保持與下一行對齊。 在我的情況下(使用 Apache Netbeans)它被正確呈現。
<blockquote><pre>...
和<pre>{@code....
之間存在顯着差異。前者將省略泛型中的類型聲明,但后者會保留它。
Eg: List<MyClass> myObject = null;
顯示為List myObject = null;
與 firts 和作為List<MyClass> myObject = null;
與第二
如果您是 Android 開發人員,則可以使用:
<pre class=”prettyprint”>
TODO:your code.
</pre>
使用 Java 代碼在 Javadoc 中漂亮地打印您的代碼。
其他兩種解決方案的組合似乎很完美:
* <pre>{@code
* {@literal @}Override
* public void someMethod() {
* Set<String> s;
* }
* }</pre>
IE。 使用<pre>{@code
開始和}</pre>
結束代碼段。 另外,將@
替換為{@literal @}
。
還沒有找到更簡單的解決方案。 對於幾十年來一直在積極發展的語言來說,這很令人難過。
我剛剛在這里閱讀了 Javadoc 1.5 參考,只有帶有<
和>
的代碼必須包含在{@code ...}
。 這里有一個簡單的例子:
/**
* Bla bla bla, for example:
*
* <pre>
* void X() {
* List{@code <String>} a = ...;
* ...
* }
* </pre>
*
* @param ...
* @return ...
*/
.... your code then goes here ...
嘗試用“pre”替換“code”。 HTML 中的 pre 標記將文本標記為預格式化,所有換行符和空格都將在您鍵入時完全顯示。
使用 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>
*/
這會產生與常規代碼完全相同的輸出,常規代碼間距和新行保持不變。
至少在 Visual Studio Code 中,您可以通過將 Javadoc 注釋包裹在三個反引號中來強制 Javadoc 注釋遵守換行符,如下所示:
/** ```markdown
* This content is rendered in (partial) markdown.
*
* For example, *italic* and **bold** text works, but [links](https://www.google.com) do not.
* Bonus: it keeps single line-breaks, as seen between this line and the previous.
``` */
我通過這兩種方式工作沒有任何問題:
<pre>
<code>
... java code, even including annotations
</code>
</pre>
和
<pre class="code">
... java code, even including annotations
</pre>
當然后者更簡單,觀察class="code"
部分
從 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
*/
我用<pre class="brush: java"></pre>
標簽附上了我的示例代碼,並使用SyntaxHighlighter來發布 javadoc。 它不會損害 IDE,並使發布的代碼示例美觀。
聲明:本站的技術帖子網頁,遵循CC BY-SA 4.0協議,如果您需要轉載,請注明本站網址或者原文地址。任何問題請咨詢:yoyou2525@163.com.