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>タグに加えて、@codeJavaDocアノテーションも使用する必要があります。これにより、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);

（参考までに、Java SE 8タグの説明はここにあります：Javadocタグ）

特定のコード例をjavadocコメントに含めるのは本当に大変でした。これを共有したいと思います。
次の点に注意してください：

• old- <code>タグを使用して、中括弧が解釈されないようにします
• 「new」の使用法{@code ...}-出力に含まれるジェネリックを取得するためのタグ
• @Override「{@literal @}Override」を介した@記号のエスケープ
• 前にスペースを1つ削除する{@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();

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行に表示されるためです。

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に示す次のスニペットを使用して、見栄えの良い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行に分割されています。コード2は、図2に示すように、生成されたjavadoc HTMLファイルを生成します。

< pre> A-->B \ C-->D \ \ G E-->F

（図2）

スティーブBの提案（コード3）は最良の結果を与えるようで、Alt + Shift + Fを押した後も期待どおりにフォーマットされたままです。

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

（コード3）

コード3を使用すると、図1に示すのと同じjavadoc HTML出力が生成されます。

これが私の2セントです。

すでに状態他の回答として、あなたは使うべき<pre> </pre>で接続詞で{@code }。

使用preして{@code}

• コードを内部にラップし、コードが1行に折りたたまれるの<pre>を</pre>防ぎます。
• コードを内側にラップする{@code }ことで<、>とその間のすべてが消えることを防ぎます。これは、コードにジェネリックまたはラムダ式が含まれている場合に特に便利です。

注釈の問題

コードブロックに注釈が含まれている場合、問題が発生する可能性があります。これは@、Javadoc行の先頭に記号が表示されると、@paramまたはのようなJavadocタグと見なされるためと考えられ@returnます。たとえば、次のコードは正しく解析されない可能性があります。

/**
 * Example usage:
 *
 * <pre>{@code
 * @Override
 * public void someOverriddenMethod() {

上記のコードは私の場合完全に消えます。

これを修正するには、行が@記号で始まってはなりません。

/**
 * Example usage:
 *
 * <pre>{@code  @Override
 * public int someMethod() {
 *     return 13 + 37;
 * }
 * }</pre>
 */

@codeとの間に2つのスペースがあり@Override、次の行に揃えるために注意してください。私の場合（Apache Netbeansを使用）、正しくレンダリングされます。

間に有意な差がある<blockquote><pre>...と<pre>{@code....、前者はジェネリックで型宣言を省略しますが、後者はそれを維持しますが。

E.g.: List<MyClass> myObject = null;List myObject = null;最初と同じようList<MyClass> myObject = null;に、2番目と同じように 表示されます

あなたがAndroid開発者ならあなたは使うことができます：

<pre class=”prettyprint”>

TODO:your code.

</pre>

JavadocでJavaコードを使用してコードをきれいに印刷する。

「code」を「pre」に置き換えてみてください。HTMLの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 ...

私はサンプルコードを<pre class="brush: java"></pre>タグで囲み、公開されたjavadocsにはSyntaxHighlighterを使用します。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>
 */

これにより、通常のコード間隔と改行はそのままで、通常のコードとまったく同じように見える出力が生成されます。

少なくともVisual Studio Codeでは、以下に示すように、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.
 ``` */