Quelle balise doit être utilisée comme séparateur de paragraphe dans Javadoc ?

Question

Quelle est la balise HTML la plus appropriée pour séparer les paragraphes/longues sections de la javadoc, conformément aux meilleures pratiques ?

Est-ce que c'est <p /> ou <br /> ? Pourquoi ?

Answer 1

Bienvenue au pays du HTML 3.2.

Selon le guide officiel sur la rédaction des commentaires de doc, la façon correcte de séparer les paragraphes est d'utiliser la balise paragraph : <P> . Jetez un coup d'œil à la septième puce de la section sur les Format d'un commentaire de document .

D'ordinaire, je déconseille fortement l'utilisation de pratiques aussi anciennes et dépassées pour le balisage. Cependant, dans ce cas, il y a une bonne raison de faire une exception. L'outil Javadoc (à moins qu'il ne soit radicalement mis à jour avec des Doclets personnalisés) génère un balisage ancien, lourd et quelque peu défectueux. Les navigateurs ont été conçus pour être rétrocompatibles avec le vieux balisage de l'époque, il est donc logique que vous vous y pliez. Votre utilisation de <P> pour séparer les paragraphes sera en accord avec le reste de la sortie Javadoc.

Answer 2

A proprement parler, une fermeture automatique <p /> n'a aucun sens, car <p> doit être utilisé pour contiennent un paragraphe, c'est-à-dire que le paragraphe doit être entouré de <p> y </p> .

<br> est toutefois une balise de "niveau inférieur" qui indique un saut de ligne. Ainsi, la manière sémantiquement correcte d'indiquer les paragraphes serait d'utiliser la balise <p> :

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

vs.

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

Visuellement, le <p> permet de laisser plus d'espace entre les lignes, tandis que l'option <br> va juste commencer une nouvelle ligne et ne pas introduire d'espace majeur.

Answer 3

Avec Java 8, un seul élément de départ( <p> ) fonctionne.

Notez que javadoc n'aime pas l'élément de fermeture ( </p> ).