Ví dụ mã nhiều dòng trong nhận xét Javadoc

Tôi có một ví dụ mã nhỏ mà tôi muốn đưa vào nhận xét Javadoc cho một phương thức.

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

Vấn đề là ví dụ mã hiển thị trong Javadoc không có ngắt dòng khiến nó khó đọc.

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

Tôi đoán rằng tôi đã sai khi cho rằng thẻ mã sẽ xử lý ngắt dòng. Cách tốt nhất để định dạng các ví dụ mã trong các bình luận Javadoc là gì?

Ngoài các <pre>thẻ đã được đề cập , bạn cũng nên sử dụng @codechú thích JavaDoc, điều này sẽ giúp cuộc sống dễ dàng hơn nhiều khi gặp các vấn đề về thực thể HTML (đặc biệt là với Generics), ví dụ:

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

Sẽ cung cấp đầu ra HTML chính xác:

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

Trong khi bỏ qua @codekhối (hoặc sử dụng <code>thẻ) sẽ dẫn đến HTML như thế này:

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

(Để tham khảo, có thể tìm thấy các mô tả thẻ Java SE 8 tại đây: Thẻ Javadoc )

Tôi đã có một thời gian thực sự khó khăn với việc đưa một ví dụ mã cụ thể vào một bình luận javadoc. Tôi muốn chia sẻ cái này
Xin lưu ý những điều sau:

• sử dụng <code>thẻ cũ để ngăn các dấu ngoặc nhọn không bị hiểu
• sử dụng {@code ...}thẻ "mới" - để có được tổng quát bao gồm trong đầu ra
• thoát khỏi đăng nhập @ @Overridethông qua " {@literal @}Override" vì trình tạo javadoc "nghiêng" ở đó do thực tế là @ đi trực tiếp sau một dấu ngoặc nhọn mở
• xóa một khoảng trống ở phía trước {@codevà {@literal, để bù các khoảng trống bên trong và giữ căn chỉnh

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

được in như

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

Nguồn java có rất nhiều ví dụ hay cho việc này. Đây là một ví dụ từ phần đầu của "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>
...

Kèm theo mã multiline của bạn với <pre></pre>các thẻ.

Bạn cần các <pre></pre>thẻ cho ngắt dòng và {@code ... }bên trong chúng cho tổng quát. Nhưng sau đó, không được phép đặt dấu ngoặc mở trên cùng một dòng với <generic>thẻ, vì sau đó mọi thứ sẽ được hiển thị lại trên 1 dòng.

Hiển thị trên một dòng:

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

Hiển thị với ngắt dòng:

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

Một điều kỳ lạ là khi bạn dán nẹp đóng {@code, nó sẽ được hiển thị:

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

Đầu ra:

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

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

• <pre/> là cần thiết để bảo quản các dòng.
• {@code phải có dòng riêng
• <blockquote/> chỉ để thụt.

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

Các yêu cầu tối thiểu cho các mã thích hợp là <pre/>và {@code}.

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

sản lượng

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

Và một tùy chọn xung quanh <blockquote/>chèn một vết lõm.

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

sản lượng

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

Chèn <p>hoặc xung quanh với <p>và </p>mang lại cảnh báo.

Tôi đã có thể tạo các tệp HTML ưa nhìn với snip sau - nó được hiển thị trong Mã 1.

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

(Mã 1)

Mã 1 biến thành trang HTML javadoc được tạo trong Hình 1, như mong đợi.

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

(Hình 1)

Tuy nhiên, trong NetBeans 7.2, nếu bạn nhấn Alt + Shift + F (để định dạng lại tệp hiện tại), Mã 1 sẽ chuyển sang Mã 2.

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

(Mã 2)

nơi đầu tiên <pre>bây giờ được chia thành hai dòng. Mã 2 tạo ra tệp HTML javadoc được tạo như trong Hình 2.

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

(Hình 2)

Đề xuất của Steve B (Mã 3) dường như cho kết quả tốt nhất và vẫn được định dạng như mong đợi ngay cả sau khi nhấn Alt + Shift + F.

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

(Mã 3)

Việc sử dụng Mã 3 tạo ra cùng một đầu ra HTML javadoc như trong Hình 1.

Đây là hai xu của tôi.

Như các câu trả lời khác đã nêu, bạn nên sử dụng <pre> </pre>kết hợp với {@code }.

Sử dụng prevà{@code}

• Gói mã của bạn bên trong <pre>và </pre>ngăn mã của bạn sụp đổ vào một dòng;
• Gói mã của bạn bên trong {@code }ngăn chặn <, >và tất cả mọi thứ ở giữa từ biến mất. Điều này đặc biệt hữu ích khi mã của bạn chứa các biểu thức generic hoặc lambda.

Các vấn đề với chú thích

Các vấn đề có thể phát sinh khi khối mã của bạn chứa một chú thích. Đó có lẽ là vì khi @dấu hiệu xuất hiện ở đầu dòng Javadoc, nó được coi là thẻ Javadoc như @paramhay @return. Ví dụ: mã này có thể được phân tích cú pháp không chính xác:

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

Mã trên sẽ biến mất hoàn toàn trong trường hợp của tôi.

Để khắc phục điều này, dòng không được bắt đầu bằng một @dấu hiệu:

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

Lưu ý rằng có hai khoảng cách giữa @codevà @Override, để giữ mọi thứ được căn chỉnh với các dòng tiếp theo. Trong trường hợp của tôi (sử dụng Apache Netbeans), nó được hiển thị chính xác.

Có một sự khác biệt đáng kể giữa <blockquote><pre>...và <pre>{@code....Cái trước sẽ bỏ qua các khai báo kiểu trong tổng quát nhưng cái sau sẽ giữ nó.

E.g.: List<MyClass> myObject = null; hiển thị như List myObject = null;với fairs và như List<MyClass> myObject = null;với thứ hai

Nếu bạn là nhà phát triển Android, bạn có thể sử dụng:

<pre class=”prettyprint”>

TODO:your code.

</pre>

Để in đẹp mã của bạn trong Javadoc bằng mã Java.

Hãy thử thay thế "mã" bằng "trước". Thẻ trước trong HTML đánh dấu văn bản là được định dạng sẵn và tất cả các dòng và khoảng trắng sẽ xuất hiện chính xác khi bạn nhập chúng.

Tôi chỉ đọc tài liệu tham khảo Javadoc 1.5 ở đây và chỉ có mã có <và >phải được đính kèm bên trong {@code ...}. Đây là một ví dụ đơn giản:

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

Tôi kèm theo mã ví dụ của mình với <pre class="brush: java"></pre>các thẻ và sử dụng SyntaxHighlighter cho javadocs được xuất bản. Nó không làm tổn thương IDE và làm cho các ví dụ mã được xuất bản trở nên đẹp.

Sử dụng Java SE 1.6, có vẻ như tất cả các định danh UPPERCASE PRE là cách tốt nhất để làm điều này trong Javadoc:

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

là cách đơn giản nhất để làm điều này.

Một ví dụ từ javadoc tôi nhận được từ phương thức java.awt.Event:

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

Điều này tạo ra đầu ra trông giống hệt như mã thông thường, với các khoảng cách mã thông thường và các dòng mới còn nguyên vẹn.

Ít nhất trong Visual Studio Code, bạn có thể buộc một bình luận Javadoc tôn trọng ngắt dòng bằng cách gói nó trong ba backticks, như được thấy dưới đây:

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