Опишите синтаксис javadoc-комментария (1/2)

Javadoc-комментарии к классам и их членам заключаются между /** и */. С точки зрения синтаксиса Java это обычные многострочные комментарии, но вторая * позволяет различным инструментам воспринимать их как документацию API. Изначально для этого использовалась стандартная утилита javadoc, которая генерировала HTML-документацию, сейчас джавадок активно используется прямо в IDE.

До Java 1.4 каждая строка комментария обязана была начинаться со *. Сейчас это требование необязательное, но следовать ему всё ещё принято.

Первое предложение комментария принимается в качестве заголовка описания элемента. В HTML именно оно попадает на страницу индекса. Предложение заканчивается точкой с последующим разделительным символом.

В javadoc разрешено использовать HTML-теги. Фрагменты кода рекомендуется обрамлять тегом <code>, для списка с буллетами применяется <ul>, параграфы отделяются <p>. В документации библиотеки Reactor активно используются <img> с диаграммами.

#Инструменты

Опишите синтаксис javadoc-комментария (2/2)

Комментарий состоит из двух частей: описание и блок тегов. Первый блок содержит всю информацию в свободной форме. Во втором находятся теги (ранее уже упоминали их). Каждый тег начинается с новой строки, через пробел за ним следует значение.

Один тег можно использовать в блоке описания – @link. Он не обязан быть на новой строке, обрамляется фигурными скобками, и при рендеринге превращается в <a> со ссылкой на другую страницу документации.

Среди всех тегов обязательными считаются только @param для каждого параметра метода, и @return для не-void методов. Они применимы только для методов. А теги @author и @version наоборот, используются только в документации классов. Остальные блочные теги можно использовать везде:

• @deprecated
• @exception (то же что @throws)
• @see
• @since
• @serial (то же что @serialField или @serialData)

Теги @author, @param, @throws и @see могут входить в один комментарий в нескольких экземплярах.

#Инструменты