Beispiel für mehrzeiligen Code im Javadoc-Kommentar

Ich habe ein kleines Codebeispiel, das ich in den Javadoc-Kommentar für eine Methode aufnehmen möchte.

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

Das Problem ist, dass das Codebeispiel im Javadoc ohne Zeilenumbrüche angezeigt wird, was das Lesen erschwert.

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

Ich glaube, ich bin falsch in der Annahme, dass das Code-Tag Zeilenumbrüche verarbeiten würde. Wie lassen sich Codebeispiele in Javadoc-Kommentaren am besten formatieren?

Zusätzlich zu den bereits erwähnten <pre>Tags sollten Sie auch die @codeJavaDoc-Annotation verwenden, die das Leben bei Problemen mit HTML-Entitäten (insbesondere bei Generics) erheblich erleichtert, z.

* <pre>
* {@code
* Set<String> s;
* System.out.println(s);
* }
* </pre>

Gibt die korrekte HTML-Ausgabe:

Set<String> s;
System.out.println(s);

Wenn Sie den @codeBlock weglassen (oder ein <code>Tag verwenden), erhalten Sie HTML wie folgt:

Set s;
System.out.println(s);

(Als Referenz finden Sie Java SE 8-Tag-Beschreibungen hier: Javadoc-Tags )

Es fiel mir wirklich schwer, ein bestimmtes Codebeispiel in einen Javadoc-Kommentar aufzunehmen. Ich würde diesen gerne teilen.
Bitte beachten Sie Folgendes:

• Verwendung von alten <code> Tags, um zu verhindern, dass die geschweiften Klammern interpretiert werden
• Verwendung von "neu" {@code ...} -Tags, um die in der Ausgabe enthaltenen Generika zu erhalten
• Escapezeichen der @ Anmeldung @Overridevia "{@literal @}Override ", da der Javadoc-Generator dort "kippt", da das @ direkt nach einer sich öffnenden geschweiften Klammer verläuft
• Entfernen Sie ein Leerzeichen vor {@codeund {@literal, um Innenräume auszugleichen und die Ausrichtung beizubehalten

Javadoc-Code:

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

wird gedruckt als

new BeanTranslator.Builder()
  .translate(
    new Translator<String, Integer>(String.class, Integer.class){
      @Override
      public Integer translate(String instance) {
        return Integer.valueOf(instance);
      }})
  .build();

Die Java-Quelle hat viele gute Beispiele dafür. Hier ist ein Beispiel aus dem Kopf von "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>
...

Fügen Sie Ihren mehrzeiligen Code <pre></pre>Tags hinzu.

Sie benötigen die <pre></pre>Tags für die Zeilenumbrüche und die {@code ... }darin enthaltenen für Generika. Aber dann ist es nicht erlaubt, die Öffnungsklammer auf der gleichen Linie wie die zu platzieren<generic> Tag platziert werden, da dann wieder alles in einer Zeile angezeigt wird.

Zeigt in einer Zeile an:

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

Anzeigen mit Zeilenumbrüchen:

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

Eine andere seltsame Sache ist, wenn Sie die schließende Klammer von einfügen {@code, wird es angezeigt:

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

Ausgabe:

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

/**
 * <blockquote><pre>
 * {@code
 * public Foo(final Class<?> klass) {
 *     super();
 *     this.klass = klass;
 * }
 * }
 * </pre></blockquote>
 **/

• <pre/> wird zum Erhalt von Linien benötigt.
• {@code must hat eine eigene Linie
• <blockquote/> ist nur zum Einrücken.

public Foo(final Class<?> klass) {
    super();
    this.klass = klass;
}

Die Mindestanforderungen für ordnungsgemäße Codes sind <pre/>und {@code}.

/**
 * test.
 *
 * <pre>{@code
 * <T> void test(Class<? super T> type) {
 *     System.out.printf("hello, world\n");
 * }
 * }</pre>
 */

ergibt

 <T> void test(Class<? super T> type) {
     System.out.printf("hello, world\n");
 }

Und eine optionale Umgebung <blockquote/>fügt eine Einkerbung ein.

/**
 * test.
 *
 * <blockquote><pre>{@code
 * <T> void test(Class<? super T> type) {
 *     System.out.printf("hello, world\n");
 * }
 * }</pre></blockquote>
 */

ergibt

     <T> void test(Class<? super T> type) {
         System.out.printf("hello, world\n");
     }

Einfügen <p>oder umgeben mit <p>und </p>gibt Warnungen aus.

Ich konnte gut aussehende HTML-Dateien mit dem folgenden in Code 1 gezeigten Snip-It generieren.

 * <pre>
 * {@code
 * A-->B
 *  \
 *   C-->D
 *    \   \
 *     G   E-->F
 * }
 *</pre>

(Code 1)

Code 1 wurde erwartungsgemäß zur generierten Javadoc-HTML-Seite in Abb. 1.

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

(Abb. 1)

Wenn Sie in NetBeans 7.2 jedoch Alt + Umschalt + F drücken (um die aktuelle Datei neu zu formatieren), wird Code 1 zu Code 2.

 * <
 * pre>
 * {@code
 * A-->B
 *  \
 *   C-->D
 *    \   \
 *     G   E-->F
 * }
 * </pre>

(Code 2)

wo die erste <pre>ist jetzt auf zwei Zeilen gebrochen. Code 2 erzeugt eine generierte Javadoc-HTML-Datei, wie in Abb. 2 gezeigt.

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

(Abb. 2)

Der Vorschlag von Steve B (Code 3) scheint die besten Ergebnisse zu liefern und bleibt auch nach dem Drücken von Alt + Umschalt + F wie erwartet formatiert.

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

(Code 3)

Die Verwendung von Code 3 erzeugt die gleiche Javadoc-HTML-Ausgabe wie in Abb. 1 gezeigt.

Hier sind meine zwei Cent.

Wie die anderen Antworten bereits besagen, sollten Sie <pre> </pre>in Verbindung mit verwenden {@code }.

Verwenden Sie preund{@code}

• Wickeln Sie Ihren Code ein <pre>und </pre>verhindern Sie, dass Ihr Code in einer Zeile zusammenfällt.
• Das Einwickeln Ihres Codes {@code }verhindert <, dass >alles dazwischen verschwindet. Dies ist besonders nützlich, wenn Ihr Code Generika oder Lambda-Ausdrücke enthält.

Probleme mit Anmerkungen

Probleme können auftreten, wenn Ihr Codeblock eine Anmerkung enthält. Dies liegt wahrscheinlich daran, dass das @Zeichen am Anfang der Javadoc-Zeile als Javadoc-Tag wie @paramoder betrachtet wird @return. Beispielsweise könnte dieser Code falsch analysiert werden:

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

Der obige Code verschwindet in meinem Fall vollständig.

Um dies zu beheben, darf die Zeile nicht mit einem @Zeichen beginnen:

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

Beachten Sie, dass zwischen @codeund zwei Leerzeichen stehen @Override, um die Ausrichtung auf die nächsten Zeilen zu gewährleisten. In meinem Fall (mit Apache Netbeans) wird es korrekt gerendert.

Es gibt einen signifikanten Unterschied zwischen <blockquote><pre>...und <pre>{@code....Ersteres lässt die Typdeklarationen in Generika aus, Letzteres behält sie jedoch bei.

E.g.: List<MyClass> myObject = null; zeigt wie List myObject = null;bei den ersten und wie List<MyClass> myObject = null;bei der zweiten

Wenn Sie Android-Entwickler sind, können Sie verwenden:

<pre class=”prettyprint”>

TODO:your code.

</pre>

So drucken Sie Ihren Code in Javadoc mit Java-Code.

Versuchen Sie, "Code" durch "pre" zu ersetzen. Das Pre-Tag in HTML markiert den Text als vorformatiert und alle Zeilenvorschübe und Leerzeichen werden genau so angezeigt, wie Sie sie eingeben.

Ich habe gerade die Javadoc 1.5-Referenz hier gelesen und nur den Code mit <und >muss darin enthalten sein {@code ...}. Hier ein einfaches Beispiel:

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

Ich füge meinen Beispielcode <pre class="brush: java"></pre>Tags hinzu und verwende SyntaxHighlighter für veröffentlichte Javadocs. Es schadet der IDE nicht und macht veröffentlichte Codebeispiele schön.

Unter Verwendung von Java SE 1.6 scheinen alle UPPERCASE PRE-Bezeichner der beste Weg zu sein, dies in Javadoc zu tun:

/**
 * <PRE>
 * insert code as you would anywhere else
 * </PRE>
 */

ist der einfachste Weg, dies zu tun.

Ein Beispiel aus einem Javadoc, das ich von einer java.awt.Event-Methode erhalten habe:

/**
 * <PRE>
 *    int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
 *    int offmask = CTRL_DOWN_MASK;
 *    if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
 *        ...
 *    }
 * </PRE>
 */

Dies erzeugt eine Ausgabe, die genau wie der reguläre Code aussieht, wobei die regulären Code-Abstände und neuen Zeilen intakt sind.

Zumindest in Visual Studio Code können Sie einen Javadoc-Kommentar zwingen, Zeilenumbrüche zu berücksichtigen, indem Sie ihn in Triple-Backticks einschließen, wie unten dargestellt:

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