Javadoc yorumunda birden çok satır kodu örneği

Bir yöntem için Javadoc yorum eklemek istediğiniz küçük bir kod örneği var.

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

Sorun, kod örneğinin Javadoc'da satır sonları olmadan gösterilmesini zorlaştırıyor.

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

Kod etiketi satır sonları ele alacağını varsayarak yanlış sanırım. Javadoc yorumlarında kod örneklerini formatlamanın en iyi yolu nedir?

Daha önce bahsedilen <pre>etiketlere @codeek olarak, HTML varlık sorunları (özellikle de Generics ile ilgili) söz konusu olduğunda hayatı çok daha kolaylaştıracak JavaDoc ek açıklamasını da kullanmalısınız , örneğin:

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

Doğru HTML çıktısını verecektir:

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

@codeBloğu atlarken (veya bir <code>etiketi kullanırken ) şu şekilde HTML ile sonuçlanır:

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

(Referans olarak, Java SE 8 etiketi açıklamalarını burada bulabilirsiniz: Javadoc Etiketleri )

Javadoc yorumunda belirli bir kod örneği dahil ile gerçekten zor bir zaman geçirdim. Bunu paylaşmak istiyorum.
Lütfen aşağıdakilere dikkat edin:

• <code>kıvrımlı parantezlerin yorumlanmasını önlemek için eski etiket kullanılması
• "new" kullanımı {@code ...}- çıktıya dahil edilen jenerikleri almak için etiket
• @ işareti @Override" {@literal @}Override" üzerinden @ kaçan çünkü javadoc jeneratör "bir açılış kıvırcık dirsek sonra doğrudan gidiyor gerçeği nedeniyle orada" yatırır "
• önündeki bir boşluğu çıkarın {@codeve {@literaliç boşlukları telafi etmek ve hizalamayı korumak için

javadoc kodu:

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

olarak yazdırılır

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

Java kaynağının bunun için birçok iyi örneği var. İşte "String.java" başından bir örnek:

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

Çok satırlı kodunuzu <pre></pre>etiketlerle içine alın .

<pre></pre>Satır kesmeleri için etiketlere ve {@code ... }jenerikler için iç kısımlara ihtiyacınız vardır. Ancak, açılış ayracı <generic>etiketi ile aynı satıra yerleştirilmesine izin verilmez , çünkü o zaman her şey tekrar 1 satırda görüntülenir.

Bir satırdaki görüntüler:

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

Satır kesmeleri olan ekranlar:

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

Bir başka garip şey, kapanış ayracı yapıştırdığınızda, {@codegörüntüleniyor:

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

Çıktı:

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

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

• <pre/> hatları korumak için gereklidir.
• {@code kendi çizgisine sahip olmalı
• <blockquote/> sadece girinti içindir.

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

Doğru kodlar için minimum gereksinimler <pre/>ve {@code}.

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

verim

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

Ve isteğe bağlı bir çevre <blockquote/>bir girinti ekler.

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

verim

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

Takma <p>veya çevreleyen <p>ve </p>verimleri uyarılar.

Kod 1'de gösterilen aşağıdaki snip ile iyi görünümlü HTML dosyaları üretmeyi başardım.

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

(Kod 1)

Kod 1, beklendiği gibi Şekil 1'de oluşturulan javadoc HTML sayfasına dönüştü.

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

(Şek. 1)

Ancak NetBeans 7.2'de, Alt + ÜstKrktr + F tuşlarına basarsanız (geçerli dosyayı yeniden biçimlendirmek için), Kod 1 Kod 2'ye döner.

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

(Kod 2)

burada ilki <pre>iki satıra bölünmüştür. Kod 2, Şekil 2'de gösterildiği gibi oluşturulan javadoc HTML dosyasını üretir.

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

(İncir. 2)

Steve B'nin önerisi (Kod 3) en iyi sonuçları veriyor gibi görünüyor ve Alt + ÜstKrktr + F tuşlarına basıldıktan sonra bile beklendiği gibi biçimlendirilmiş olarak kalıyor.

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

(Kod 3)

Kod 3'ün kullanımı, Şekil 1'de gösterilenle aynı javadoc HTML çıktısını üretir.

İşte benim iki sentim.

Diğer cevaplar zaten belirtildiği gibi, <pre> </pre>birlikte kullanmalısınız {@code }.

Kullan preve{@code}

• İç kodunuzu tamamlayan <pre>ve </pre>bir satır üzerine çöken verdiği kodu önler;
• İçerideki kod tamamlayan {@code }önler <, >yok olmaktan arasında ve her şeyi. Bu özellikle kodunuz jenerikler veya lambda ifadeleri içeriyorsa kullanışlıdır.

Ek açıklamalarla ilgili sorunlar

Kod bloğunuz bir ek açıklama içerdiğinde sorunlar oluşabilir. Muhtemelen @işaret Javadoc satırının başında göründüğünde, @paramveya gibi bir Javadoc etiketi olarak kabul edilir @return. Örneğin, bu kod yanlış şekilde ayrıştırılabilir:

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

Yukarıdaki kod benim durumumda tamamen kaybolacak.

Bunu düzeltmek için çizgi bir @işaretle başlamamalıdır :

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

@codeVe @Overrideöğelerinin sonraki satırlarla hizalanmasını sağlamak için ve arasında iki boşluk olduğunu unutmayın . Benim durumumda (Apache Netbeans kullanarak) doğru şekilde işlenir.

Arasında önemli bir fark var <blockquote><pre>...ve <pre>{@code....birincisi jeneriklerdeki tür bildirimlerini atlayacak, ancak ikincisi bunu koruyacaktır.

E.g.: List<MyClass> myObject = null; olarak görüntüler List myObject = null;giderim çalışmalarına ve sıra List<MyClass> myObject = null;ikinci ile

Android geliştiricisiyseniz şunları kullanabilirsiniz:

<pre class=”prettyprint”>

TODO:your code.

</pre>

Java koduyla Javadoc'ta kodunuzu güzel yazdırmak için.

"Kod" yerine "pre" yazmayı deneyin. HTML'deki ön etiket metni önceden biçimlendirilmiş olarak işaretler ve tüm satır beslemeleri ve boşluklar tam olarak siz yazdıkça görünür.

Sadece Javadoc 1.5 referansı okumak burada birlikte ve sadece kod <ve >içini içine alınmalıdır {@code ...}. İşte basit bir örnek:

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

Ben ile benim örnek kod içine <pre class="brush: java"></pre>etiketleri ve kullanım SyntaxHighlighter yayınlanan javadocs için. IDE'ye zarar vermez ve yayınlanan kod örneklerini güzelleştirir.

Java SE 1.6 kullanarak, tüm UPPERCASE PRE tanımlayıcıları Javadoc'ta bunu yapmanın en iyi yolu gibi görünüyor:

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

bunu yapmanın en basit yoludur.

Bir javadoc örneği Bir java.awt.Event yönteminden aldım:

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

Bu, normal kod aralıkları ve yeni satırlar bozulmamış olarak normal koda benzeyen çıktı üretir.

En azından Visual Studio Code'da, bir Javadoc yorumunu, aşağıda görüldüğü gibi, üçlü backticks ile sararak satır sonlarına saygı göstermeye zorlayabilirsiniz:

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