У меня есть небольшой пример кода, который я хочу включить в комментарий Javadoc для метода.
/**
* -- 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
*/
Проблема в том, что пример кода отображается в Javadoc без разрывов строк, что затрудняет его чтение.
-- 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
Я предполагаю, что я ошибаюсь, предполагая, что тег кода будет обрабатывать разрывы строк Каков наилучший способ форматировать примеры кода в комментариях Javadoc?
У меня было действительно тяжелое время с включением конкретного примера кода в комментарий Javadoc. Я хотел бы поделиться этим.
Пожалуйста, обратите внимание на следующее:
<code>
тега для предотвращения интерпретации фигурных скобок{@code ...}
тега «new» для получения обобщенных элементов, включенных в вывод@Override
через "{@literal @}Override
", поскольку генератор javadoc "наклоняется" туда из-за того, что @ идет сразу после открывающей фигурной скобки{@code
и{@literal
, чтобы компенсировать внутренние пробелы и сохранить выравниваниекод Javadoc:
печатается как
источник
У источника java есть много хороших примеров для этого. Вот пример из главы "String.java":
источник
<pre><blockquote>...</blockquote></pre>
<p><blockquote><pre>
</pre></blockquote></p>
List<String>
. Для этого я использую<pre>{@code ... }</pre>
.Вложите свой многострочный код с
<pre></pre>
тегами.источник
Вам нужны
<pre></pre>
теги для разрывов строк, а{@code ... }
внутри они для обобщений. Но тогда нельзя размещать открывающую скобку на той же строке, что и<generic>
тег, потому что тогда все снова будет отображаться на 1 строке.Отображает в одной строке:
Отображает с переносами строк:
Еще одна странная вещь, когда вы вставляете закрывающую скобку
{@code
, она отображается:Вывод:
источник
...
``). Вам не нужны<code>
и<pre>
теги. Я отредактировал ваш ответ в этом уме.<pre/>
требуется для сохранения строк.{@code
должен иметь свою собственную линию<blockquote/>
только для отступа.ОБНОВЛЕНИЕ с JDK8
Минимальные требования для правильных кодов
<pre/>
и{@code}
.доходность
И необязательное окружение
<blockquote/>
вставляет отступ.доходность
Вставка
<p>
или окружение с<p>
и</p>
выдает предупреждения.источник
Я смог создать красивый HTML-файл с помощью следующего фрагмента кода, показанного в коде 1.
(Код 1)
Код 1 превратился в сгенерированную HTML-страницу javadoc на рис. 1, как и ожидалось.
(Рисунок 1)
Однако в NetBeans 7.2, если вы нажмете Alt + Shift + F (чтобы переформатировать текущий файл), Код 1 превращается в Код 2.
(Код 2)
где первый
<pre>
теперь разбит на две строки. Код 2 создает сгенерированный файл Javadoc HTML, как показано на рисунке 2.(Рис 2)
Предложение Стива Б (Код 3), кажется, дает лучшие результаты и остается отформатированным, как и ожидалось, даже после нажатия Alt + Shift + F.
(Код 3)
Использование кода 3 приводит к тому же выводу javadoc HTML, как показано на рисунке 1.
источник
Вот мои два цента.
Поскольку другие ответы уже заявляют, вы должны использовать
<pre>
</pre>
в сочетании с{@code
}
.Используйте
pre
и{@code}
<pre>
и</pre>
предотвращение свертывания кода в одну строку;{@code
}
предотвращает<
,>
и все между ними исчезает. Это особенно полезно, когда ваш код содержит обобщенные или лямбда-выражения.Проблемы с аннотациями
Проблемы могут возникнуть, когда ваш блок кода содержит аннотацию. Вероятно, это связано с тем, что когда
@
знак появляется в начале строки Javadoc, он считается тегом Javadoc, например@param
или@return
. Например, этот код может быть проанализирован неправильно:Выше код полностью исчезнет в моем случае.
Чтобы это исправить, строка не должна начинаться со
@
знака:Обратите внимание, что между
@code
и@Override
, есть два пробела , чтобы выровнять вещи со следующими строками. В моем случае (с использованием Apache Netbeans) он отображается правильно.источник
Существует существенная разница между
<blockquote><pre>...
и тем, что<pre>{@code....
первый будет опускать объявления типов в обобщениях, но последний сохранит их.E.g.: List<MyClass> myObject = null;
отображается какList myObject = null;
с первого и какList<MyClass> myObject = null;
со вторымисточник
Если вы разработчик Android, вы можете использовать:
Чтобы красиво распечатать свой код в Javadoc с кодом Java.
источник
Попробуйте заменить «код» на «предварительно». Предварительный тег в HTML помечает текст как предварительно отформатированный, и все переводы строк и пробелы будут отображаться точно по мере их ввода.
источник
Я только что прочитал ссылку на Javadoc 1.5 здесь , и только код с
<
и>
должен быть заключен внутри{@code ...}
. Вот простой пример:источник
Я прилагаю свой пример кода с
<pre class="brush: java"></pre>
тегами и использую SyntaxHighlighter для опубликованных javadocs. Это не повредит IDE и делает опубликованные примеры кода красивыми.источник
Используя Java SE 1.6, похоже, что все идентификаторы UPPERCASE PRE - лучший способ сделать это в Javadoc:
это самый простой способ сделать это.
Пример из javadoc, который я получил из метода java.awt.Event:
Это приводит к выводу, который выглядит точно так же, как обычный код, с обычными интервалами кода и новыми строками без изменений.
источник
По крайней мере, в коде Visual Studio вы можете заставить комментарий Javadoc учитывать разрывы строк, заключив его в тройные обратные кавычки, как показано ниже:
источник