Какой тег следует использовать в качестве разделителя абзацев в Javadoc? - PullRequest
42 голосов
/ 10 марта 2011

Какой тег HTML больше подходит для разбиения абзацев / длинных разделов javadoc в соответствии с передовой практикой?

Это <p /> или <br />?Почему?

Ответы [ 3 ]

54 голосов
/ 10 марта 2011

Добро пожаловать в страну HTML 3.2.

Согласно официальному руководству по написанию комментариев к документу, правильный способ разделения абзацев - с помощью тега абзаца: <P>. Посмотрите на седьмую пулю в разделе Формат комментария к документу .

Обычно я настоятельно рекомендую не использовать такие старые, устаревшие методы для разметки. Однако в этом случае есть достойная причина сделать исключение. Инструмент JavaDoc (если радикально не обновлен с помощью пользовательских доклетов) генерирует старую, грубую, несколько сломанную разметку. Браузеры созданы с учетом обратной совместимости с безумной старой разметкой дня, поэтому имеет смысл просто согласиться с ней. Использование <P> для разделения абзацев будет соответствовать остальной части вывода JavaDoc.

29 голосов
/ 10 марта 2011

Строго говоря, самозакрывающийся <p /> не имеет смысла, так как <p> должен использоваться, чтобы содержал абзац, т.е. абзац должен быть заключен в <p> и </p>.

<br> однако это тег «нижнего уровня», который указывает на разрыв строки.Таким образом, семантически правильным способом обозначения абзацев будет использование <p>:

<p>This Foo is used to frobincate a {@link Baz}.</p>
<p>It is quite groovy!</p>

против

This Foo is used to frobincate a {@link Baz}.<br>
It is quite groovy!

Визуально <p> приводит к увеличению пробела между строками, в то время как<br> просто начнет новую строку и не будет вводить никаких пробелов.

5 голосов
/ 07 декабря 2017

В Java 8 работает один начальный элемент (<p>).

Обратите внимание, что javadoc не нравится закрывающий элемент (</p>).

...