Javadoc-комментарии к классам и их членам заключаются между /** и */. С точки зрения синтаксиса Java это обычные многострочные комментарии, но вторая * позволяет различным инструментам воспринимать их как документацию API. Изначально для этого использовалась стандартная утилита javadoc, которая генерировала HTML-документацию, сейчас джавадок активно используется прямо в IDE.
До Java 1.4 каждая строка комментария обязана была начинаться со *. Сейчас это требование необязательное, но следовать ему всё ещё принято.
Первое предложение комментария принимается в качестве заголовка описания элемента. В HTML именно оно попадает на страницу индекса. Предложение заканчивается точкой с последующим разделительным символом.
В javadoc разрешено использовать HTML-теги. Фрагменты кода рекомендуется обрамлять тегом <code>, для списка с буллетами применяется <ul>, параграфы отделяются <p>. В документации библиотеки Reactor активно используются <img> с диаграммами.
Комментарий состоит из двух частей: описание и блок тегов. Первый блок содержит всю информацию в свободной форме. Во втором находятся теги. Каждый тег начинается с новой строки, через пробел за ним следует значение.
Один тег можно использовать в блоке описания –
@link. Он не обязан быть на новой строке, обрамляется фигурными скобками, и при рендеринге превращается в <a> со ссылкой на другую страницу документации.Среди всех тегов обязательными считаются только
@param для каждого параметра метода, и @return для не-void методов. Они применимы только для методов. А теги @author и @version наоборот, используются только в документации классов. Остальные блочные теги можно использовать везде:•
@deprecated•
@exception (то же что @throws)•
@see•
@since•
@serial (то же что @serialField или @serialData)Теги
@author, @param, @throws и @see могут входить в один комментарий в нескольких экземплярах.👉@BookJava