Пример кода с несколькими строками в комментарии Javadoc

Ваша проблема с добавлением примера кода в комментарии Javadoc вполне понятна. Вот как можно правильно оформить код и избежать привычных проблем с форматированием:

Обратите внимание на следующие моменты:

• Использование устаревшего тега <code>, чтобы предотвратить интерпретацию фигурных скобок.
• Использование нового тега {@code ...} для корректного отображения обобщений в выходных данных.
• Экранирование символа @ в @Override через "{@literal @}Override", поскольку генератор Javadoc "съезжает" из-за того, что @ идет сразу после открывающей фигурной скобки.
• Удаление пробела перед {@code и {@literal, чтобы компенсировать внутренние пробелы и сохранить выравнивание.

Пример кода Javadoc выглядит следующим образом:

/**
 * Этот метод добавляет конкретный транслятор из одного типа в другой.
 * То есть:
 * <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();

Используйте этот подход, чтобы избежать распространенных проблем с форматированием в Javadoc.

В исходном коде Java можно найти множество хороших примеров для этого. Вот один из примеров из начала файла "String.java":

....
 * эквивалентен:
 * <p><blockquote><pre>
 *     char data[] = {'a', 'b', 'c'};
 *     String str = new String(data);
 * </pre></blockquote><p>
 * Вот еще несколько примеров использования строк:
 * <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>
...

Если у вас есть дополнительные вопросы, не стесняйтесь задавать!

Чтобы правильно оформить многострочный код в вашем посте на StackOverflow, оберните его в теги <pre></pre>. Это позволит сохранить форматирование и улучшит читаемость вашего кода. Пример:

<pre>
Ваш многострочный код здесь
</pre>

Если вы используете Markdown, вы также можете использовать тройные обратные кавычки (```) для обрамления кода:

Ваш многострочный код здесь

Такой способ также сохраняет форматирование и делает код более понятным для других пользователей.

Для того чтобы корректно отображать разрывы строк в вашем коде, вам необходимо использовать теги <pre></pre> и вставлять {@code ... } внутрь них для работы с обобщениями. Однако стоит помнить, что открывающую фигурную скобку нельзя ставить на одной строке с тегом <generic>, иначе это приведёт к тому, что весь код будет отображаться в одну строку.

Отображение в одну строку:

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

Корректное отображение с разрывами строк:

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

Ещё один странный момент заключается в том, что если вы вставите закрывающую фигурную скобку для {@code, то она будет отображаться:

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

Вывод будет таким:

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

Таким образом, важно следить за правильным форматированием, чтобы избежать неожиданных результатов.

Для того чтобы сохранить форматирование кода в документации на Java, необходимо использовать специальные теги. Вот пример, как можно оформить конструктор класса с использованием тегов <pre/> и {@code}:

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

В этом примере:

• Тег <pre/> используется для сохранения форматирования кода.
• Директива {@code} должна находиться на отдельной строке.
• Обрамляющий тег <blockquote/> добавляет отступ, что помогает в улучшении читаемости.

Если вы используете JDK8, то для правильного отображения кода в документации обязателен стиль с тегами <pre/> и {@code}:

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

Результатом будет следующий форматированный текст:

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

Также добавление обрамляющего тега <blockquote/> позволит вставить отступ:

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

Это приведет к следующему результату:

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

Следует избегать использования тега <p> или обрамления кода с помощью <p> и </p>, так как это приведет к предупреждениям.