web-dev-qa-db-ja.com

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

Codeタグが改行を処理すると仮定するのが間違っていると思います。 Javadocコメントのコード例をフォーマットするための最良の方法は何ですか？

javahtmljavadoc
503
Mark

既に述べた<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);

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

712
Fabian Steeg

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

  • 古い<code> - 中括弧が解釈されないようにするタグの使い方
  • "new" {@code ...}の使用法 - 出力に含まれる総称を取得するためのタグ
  • @は左中括弧の直後に置かれるため、javadocジェネレータが "傾く"ため、 "@Override"を介して{@literal @}Override内の@記号をエスケープする
  • 内側のスペースを補正して整列を維持するために、{@codeおよび{@literalの前にあるスペースを1つ削除します。

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();
156
Christoph Naber

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>
...
41
Steve B.

複数行のコードを<pre></pre>タグで囲みます。

22
Zach Scrivena

改行には<pre></pre>タグが、ジェネリックにはその中の{@code ... }が必要です。しかし、括弧を<generic>タグと同じ行に配置することは許可されていません。これは、すべて1行に表示されるためです。

1行に表示します。

* ..
* <pre>
* {@code
* public List<Object> getObjects() {
*    return objects;
* }
* </pre>
* ..

改行付きで表示します。

* ..
* <pre>
* {@code
* public List<Object> getObjects() 
* {
*    return objects;
* }
* </pre>
* ..

もう1つの奇妙なことは、{@codeの右中括弧を貼り付けると表示されることです。

* ..
* <pre>
* {@code
*   public List<Object> getObjects() 
*   {
*     return objects;
*   }
* }
* </pre>
* ..

出力：

public List<Object> getObjects() 
{
   return objects;
}
}
14
Rule

私は以下の抜粋で見栄えの良い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は、図2に示すように、生成されたjavadoc HTMLファイルを生成します。

< 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出力が生成されます。

4
bitsdanceforme

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

他の答えが既に述べているように、あなたは<pre></pre>を{@code}と一緒に使うべきです。

preと{@code}を使う

  • コードを<pre>と</pre>で囲むと、コードが1行に収まらなくなります。
  • コードを{@code}で囲むと、<、>、およびその間にあるすべてのものが消えるのを防ぐことができます。コードに総称またはラムダ式が含まれている場合、これは特に便利です。

注釈に関する問題

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

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

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

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

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

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

3
MC Emperor

<blockquote><pre>...と<pre>{@code....の間には大きな違いがあります。前者は総称の型宣言を省略しますが、後者はそれを守ります。

E.g.: List<MyClass> myObject = null;は、先頭がList myObject = null;、後半がList<MyClass> myObject = null;と表示されます。

3
Tamas

あなたがAndroidの開発者であれば、あなたは使用することができます。

<pre class=”prettyprint”>

TODO:your code.

</pre>

Javaコードを使ってJavadocのコードをきれいに印刷する。

2
ifeegoo

"code"を "pre"に置き換えてみてください。 HTMLのpreタグはテキストを整形済みとしてマークし、すべての改行とスペースは入力したとおりに表示されます。

1
Edwin

Javadoc 1.5のリファレンス をここ で読み、<と>を含むコードのみを{@code ...}で囲む必要があります。これは簡単な例です。

 /** 
 * Bla bla bla, for example:
 *
 * <pre>
 * void X() {
 *    List{@code <String>} a = ...;
 *    ...
 * }
 * </pre>
 *
 * @param ...
 * @return ...
 */
 .... your code then goes here ...
1
mljrg

Java SE 1.6を使用している場合、Javadocでこれを行うにはすべての大文字のPRE識別子が最善の方法です。

/**
 * <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>
 */

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

0
Eugene_CD-adapco

私のサンプルコードを<pre class="brush: Java"></pre>タグで囲み、公開されているjavadocに SyntaxHighlighter を使用します。それはIDEを傷つけず、公開されたコード例を美しくします。

0
Jarek Przygódzki