Форматирование примеров кода в Javadoc комментариях

Не редко при написании документации к методам возникает необходимость вставить пример кода. Это облегчает понимание работы метода и позволяет быстрее начать его использовать. Однако, встречается проблема, когда в Javadoc комментариях необходимо вставить пример кода, состоящий из нескольких строк.

Допустим, есть следующий метод и к нему написан Javadoc комментарий со вставленным примером кода:

/**
 * Переводит число в строку.
 * <code>
 * int number = 5;
 * String numberAsString = intToString(number);
 * System.out.println(numberAsString); // Выводит: "5"
 * </code>
 * @param number число, которое необходимо перевести в строку
 * @return строковое представление числа
 */
public String intToString(int number) {
    return Integer.toString(number);
}

Однако, при генерации Javadoc документации, пример кода выводится как одна строка, что затрудняет его чтение:

Переводит число в строку. int number = 5; String numberAsString = intToString(number); System.out.println(numberAsString); // Выводит: "5" Parameters: number - число, которое необходимо перевести в строку Returns: строковое представление числа

Проблема в том, что тег <code> не сохраняет переносы строк. Далее будет показано, как можно решить эту проблему.

Использование тега <pre>

В HTML есть специальный тег <pre>, который позволяет сохранить форматирование текста внутри него, включая пробелы и переносы строк. Этот тег также поддерживается Javadoc и его можно использовать для форматирования примеров кода.

Вот как можно переписать пример выше с использованием тега <pre>:

/**
 * Переводит число в строку.
 * <pre>
 * <code>
 * int number = 5;
 * String numberAsString = intToString(number);
 * System.out.println(numberAsString); // Выводит: "5"
 * </code>
 * </pre>
 * @param number число, которое необходимо перевести в строку
 * @return строковое представление числа
 */
public String intToString(int number) {
    return Integer.toString(number);
}

Теперь при генерации Javadoc документации пример кода будет выглядеть в соответствии с оформлением в исходном коде:

Переводит число в строку.
int number = 5;
String numberAsString = intToString(number);
System.out.println(numberAsString); // Выводит: "5"
Parameters: number - число, которое необходимо перевести в строку
Returns: строковое представление числа

Таким образом, использование тега <pre> позволяет сохранить форматирование примеров кода в Javadoc комментариях.