Contoh beberapa kode baris dalam komentar Javadoc

Saya punya contoh kode kecil yang ingin saya sertakan dalam komentar Javadoc untuk suatu metode.

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

Masalahnya adalah contoh kode muncul di Javadoc tanpa jeda baris sehingga sulit dibaca.

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

Saya kira saya salah mengasumsikan tag kode akan menangani jeda baris. Apa cara terbaik untuk memformat contoh kode dalam komentar Javadoc?

Selain <pre>tag yang telah disebutkan , Anda juga harus menggunakan @codeanotasi JavaDoc, yang akan membuat hidup lebih mudah ketika menyangkut masalah entitas HTML (khususnya dengan Generik), misalnya:

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

Akan memberikan hasil HTML yang benar:

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

Saat menghilangkan @codeblok (atau menggunakan <code>tag) akan menghasilkan HTML seperti ini:

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

(Untuk referensi, deskripsi tag Java SE 8 dapat ditemukan di sini: Tag Javadoc )

Saya mengalami kesulitan dengan memasukkan contoh kode spesifik dalam komentar javadoc. Saya ingin membagikan yang ini.
Harap perhatikan hal berikut:

• penggunaan <code>tag lama untuk mencegah tanda kurung keriting ditafsirkan
• penggunaan "baru" {@code ...}- tag untuk mendapatkan obat generik yang disertakan dalam output
• melarikan diri dari masuk @ @Overridemelalui " {@literal @}Override" karena generator javadoc "memiringkan" di sana karena fakta bahwa @ masuk langsung setelah braket keriting pembukaan
• menghapus satu ruang di depan {@codedan {@literal, untuk mengompensasi ruang dalam dan menjaga perataan

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

akan dicetak sebagai

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

Sumber java memiliki banyak contoh bagus untuk ini. Berikut ini contoh dari kepala "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>
...

Lampirkan kode multiline Anda dengan <pre></pre>tag.

Anda perlu <pre></pre>tag untuk jeda baris, dan {@code ... }di dalamnya untuk generik. Tapi kemudian itu tidak diperbolehkan untuk menempatkan brace pembuka pada baris yang sama dengan <generic>tag, karena kemudian semuanya akan ditampilkan pada 1 baris lagi.

Menampilkan pada satu baris:

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

Tampilan dengan jeda baris:

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

Hal aneh lainnya adalah ketika Anda menempelkan kurung kurawal {@code, itu akan ditampilkan:

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

Keluaran:

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

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

• <pre/> diperlukan untuk menjaga garis.
• {@code harus memiliki jalurnya sendiri
• <blockquote/> hanya untuk lekukan.

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

Persyaratan minimum untuk kode yang benar adalah <pre/>dan {@code}.

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

hasil panen

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

Dan opsional di sekitarnya <blockquote/>memasukkan lekukan.

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

hasil panen

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

Memasukkan <p>atau mengelilinginya <p>dan </p>menghasilkan peringatan.

Saya dapat menghasilkan file HTML yang terlihat bagus dengan snip-it yang ditunjukkan pada Kode 1.

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

(Kode 1)

Kode 1 berubah menjadi halaman HTML javadoc yang dihasilkan pada Gambar 1, seperti yang diharapkan.

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

(Gbr. 1)

Namun, di NetBeans 7.2, jika Anda menekan Alt + Shift + F (untuk memformat ulang file saat ini), Kode 1 berubah menjadi Kode 2.

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

(Kode 2)

di mana yang pertama <pre>sekarang dibagi menjadi dua baris. Kode 2 menghasilkan file HTML javadoc yang dihasilkan seperti yang ditunjukkan pada Gambar 2.

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

(Gbr 2)

Saran Steve B (Kode 3) tampaknya memberikan hasil terbaik dan tetap diformat seperti yang diharapkan bahkan setelah menekan Alt + Shift + F.

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

(Kode 3)

Penggunaan Kode 3 menghasilkan output HTML javadoc yang sama seperti yang ditunjukkan pada Gambar 1.

Ini dua sen saya.

Karena jawaban lain sudah menyatakan, Anda harus menggunakannya <pre> </pre>bersamaan {@code }.

Gunakan predan{@code}

• Membungkus kode Anda di dalam <pre>dan </pre>mencegah kode Anda runtuh ke satu baris;
• Membungkus kode Anda di dalam {@code }mencegah <, >dan segala sesuatu di antaranya menghilang. Ini sangat berguna ketika kode Anda mengandung ekspresi generik atau lambda.

Masalah dengan anotasi

Masalah dapat muncul ketika blok kode Anda berisi anotasi. Itu mungkin karena ketika @tanda muncul di awal baris Javadoc, itu dianggap sebagai tag Javadoc seperti @paramatau @return. Misalnya, kode ini dapat diuraikan secara salah:

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

Kode di atas akan hilang sepenuhnya dalam kasus saya.

Untuk memperbaiki ini, garis tidak boleh dimulai dengan @tanda:

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

Perhatikan bahwa ada dua ruang di antara @codedan @Override, untuk menjaga hal-hal sejalan dengan baris berikutnya. Dalam kasus saya (menggunakan Apache Netbeans) itu ditampilkan dengan benar.

Ada perbedaan yang signifikan antara <blockquote><pre>...dan yang <pre>{@code....pertama akan menghilangkan deklarasi tipe dalam generik tetapi yang terakhir akan menyimpannya.

E.g.: List<MyClass> myObject = null; ditampilkan seperti List myObject = null;dengan pertama dan List<MyClass> myObject = null;kedua

Jika Anda adalah pengembang Android, Anda dapat menggunakan:

<pre class=”prettyprint”>

TODO:your code.

</pre>

Untuk mencetak kode Anda dengan cantik di Javadoc dengan kode Java.

Coba ganti "kode" dengan "pra". Tag pra dalam HTML menandai teks sebagai sudah diformat dan semua baris baris dan spasi akan muncul tepat saat Anda mengetiknya.

Saya baru saja membaca referensi Javadoc 1.5 di sini , dan hanya kodenya dengan <dan >harus dilampirkan di dalamnya {@code ...}. Berikut contoh sederhana:

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

Saya menyertakan kode contoh saya dengan <pre class="brush: java"></pre>tag dan menggunakan SyntaxHighlighter untuk javadocs yang diterbitkan. Tidak ada salahnya IDE dan membuat contoh kode yang diterbitkan indah.

Menggunakan Java SE 1.6, sepertinya semua pengidentifikasi PRE UPPERCASE adalah cara terbaik untuk melakukan ini di Javadoc:

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

adalah cara paling sederhana untuk melakukan ini.

Contoh dari javadoc yang saya dapatkan dari metode java.awt.Event:

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

Ini menghasilkan output yang terlihat persis seperti kode biasa, dengan jarak kode reguler dan baris baru utuh.

Dalam Visual Studio Code setidaknya, Anda dapat memaksa komentar Javadoc untuk menghormati jeda baris dengan membungkusnya dalam triple-backticks, seperti yang terlihat di bawah ini:

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