1. Обзор
В этом руководстве мы рассмотрим различные способы форматирования комментариев Javadoc. Мы сосредоточимся на анализе форматирования фрагментов кода , написанных в виде комментариев к документации.
2. Введение
Javadoc — это инструмент для создания документации для класса Java. Он обрабатывает комментарии к документации, указанные в исходном файле Java, и генерирует соответствующую HTML-страницу .
Пожалуйста, обратитесь к нашей статье, чтобы узнать больше о документации Javadoc .
3. Фрагменты кода как комментарии Javadoc
Мы можем включать фрагменты кода как часть комментариев к документации для класса Java. Мы хотим просмотреть фрагменты кода с правильными отступами и символами на сгенерированной HTML-странице.
Давайте попробуем добавить фрагмент кода Java как часть наших комментариев:
/**
* This is an example to show default behavior of code snippet formatting in Javadocs
*
* public class Application(){
*
* }
*
*/
Соответствующая HTML-страница:
По умолчанию разрывы строк и пробелы в комментариях Javadoc не сохраняются . Это приводит к неправильному отступу, особенно в случае многострочных фрагментов кода.
Давайте найдем способ поддерживать правильные отступы в наших комментариях.
3.1. Использование тега <pre>
HTML предоставляет тег <pre> для обозначения предварительно отформатированного текста. Он сохраняет пробелы и разрывы строк заключенного текста , тем самым сохраняя необходимый отступ для фрагментов кода:
/**
* This is an example to show usage of HTML pre tag while code snippet formatting in Javadocs
*
* <pre>
* public class Application(){
* List<Integer> nums = new ArrayList<>();
* }
*
* </pre>
*/
Соответствующая HTML-страница:
Здесь мы успешно сохранили пробелы и разрывы строк, необходимые для наших фрагментов кода. Однако теперь мы столкнулись с другой проблемой: мы не можем видеть обобщения , введенные как часть фрагмента кода.
Поскольку комментарии преобразуются в HTML-страницу, части фрагментов кода могут быть неверно истолкованы как HTML-теги , например <Integer> в приведенном выше примере.
Давайте рассмотрим способы сохранения правильного форматирования символов HTML, встроенных в наши комментарии.
3.2. Использование объектов символов HTML
Если наш фрагмент кода содержит зарезервированные символы HTML, такие как ' < ', ' > ' или ' & ', они могут быть интерпретированы как символы HTML при анализе комментариев. Чтобы сохранить эти символы, мы можем использовать объекты Character вместо необходимых символов.
Например, мы можем использовать < для обозначения символа ' < ':
/**
* This is an example to show usage of HTML character entities while code snippet formatting in Javadocs
*
* <pre>
* public class Application(){
* List<Integer> nums = new ArrayList<>();
* }
*
* </pre>
*/
Соответствующая HTML-страница:
3.3. Использование тега @code
J avadoc предоставляет тег @code , который обрабатывает комментарии, заключенные в скобки, как исходный код, а не символы HTML . Это позволяет нам использовать зарезервированные символы HTML напрямую, не экранируя их с помощью сущностей символов :
/**
* This is an example to show usage of javadoc code tag while code snippet formatting in Javadocs
*
* <pre>
*
* public class Application(){
* {@code List<Integer> nums = new ArrayList<>(); }
* }
*
* </pre>
*/
Соответствующая HTML-страница:
Обратите внимание, что тег @code не решает проблемы с отступами в наших комментариях. Для этого нам нужно дополнительно использовать тег <pre> .
Как мы видели выше, Javadoc идентифицирует теги, используя символы ' @ ' . Если у нас есть ' @ ' как часть наших фрагментов кода, это будет неверно истолковано Javadoc, что приведет к неправильному отображению комментариев.
Давайте посмотрим на это на примере:
/**
* This is an example to show issue faced while using annotations in Javadocs
*
* <pre>
*
* public class Application(){
* @Getter
* {@code List<Integer> nums = new ArrayList<>(); }
* }
*
* </pre>
*/
Соответствующая HTML-страница:
Как мы видим, Javadoc обрабатывает @Getter как тег, и комментарии отображаются неправильно. Мы можем встроить аннотации (или код с использованием символов @ ) в тег @code , предоставленный Javadoc:
/**
* This is an example to show usage of javadoc code tag for handling '@' character
*
* <pre>
*
* public class Application(){
* {@code @Getter}
* {@code List<Integer> nums = new ArrayList<>(); }
* }
*
* </pre>
*/
Соответствующая HTML-страница:
3.4. Использование тега @literal
Аналогичного поведения `` можно добиться и с помощью тега @literal . Единственная разница между тегом @code и тегом @literal заключается в том, что тег @code форматирует заключенный в нем текст кодовым шрифтом :
/**
* This is an example to show difference in javadoc literal and code tag
*
* <p>
*
* {@literal @Getter}
* {@literal List<Integer> nums = new ArrayList<>(); }
*
* <br />
* {@code @Getter}
* {@code List<Integer> nums = new ArrayList<>(); }
* </p>
*/
Соответствующая HTML-страница:
Таким образом, мы добились корректного отображения фрагментов кода на HTML-странице.
3.5. Форматирование фрагментов кода jQuery
Здесь мы взяли пример фрагмента кода Java. Те же функции применимы и для любого другого языка.
Давайте включим простой фрагмент кода jQuery в качестве комментария к документации:
/**
* This is an example to illustrate a basic jQuery code snippet embedded in documentation comments
* <pre>
* {@code <script>}
* $document.ready(function(){
* console.log("Hello World!);
* })
* {@code </script>}
* </pre>
*/
Соответствующая HTML-страница:
3.6. Форматирование фрагментов HTML-кода
До сих пор мы понимали, что, с одной стороны, Javadoc позволяет нам использовать теги HTML для форматирования наших комментариев, а с другой стороны, это также может привести к проблемам, когда мы хотим использовать символы HTML без разметки.
Например, мы можем захотеть вставить фрагменты HTML-кода в наши комментарии.
Давайте вставим фрагмент HTML-кода как часть нашего комментария к документации и посмотрим, как он себя ведет:
/**
* This is an example to illustrate an HTML code snippet embedded in documentation comments
* <pre>
* <html>
* <body>
* <h1>Hello World!</h1>
* </body>
* </html>
* </pre>
*
*/
Соответствующая HTML-страница:
Здесь мы видим, что фрагмент кода, встроенный в комментарии, был преобразован в HTML-страницу с разметкой HTML . Мы можем решить проблему с помощью тега @code , как обсуждалось выше:
/**
* This is an example to illustrate an HTML code snippet embedded in documentation comments
* <pre>{@code
* <html>
* <body>
* <h1>Hello World!</h1>
* </body>
* </html>}
* </pre>
*
*/
Соответствующая HTML-страница:
4. Вывод
Мы рассмотрели различные способы форматирования комментариев Javadoc. Мы можем выбрать параметры форматирования в соответствии с нашими требованиями для создания хорошо отформатированной документации.
Мы можем использовать HTML-теги для улучшения форматирования комментариев Javadoc, а также избегать их, когда это соответствует нашим требованиям.