Quelle balise doit être utilisée comme séparateur de paragraphe dans Javadoc?
Quelle est la balise HTML la plus appropriée pour décomposer les paragraphes/longues sections de javadoc selon les meilleures pratiques?
Est-ce <p /> ou <br />? Pourquoi?
Bienvenue au pays du HTML 3.2.
Selon le guide officiel sur la rédaction des commentaires de doc, la bonne façon de séparer les paragraphes est d'utiliser la balise de paragraphe: <P>. Jetez un oeil à la septième puce dans la section sur Format d'un commentaire de document .
Habituellement, je déconseille fortement d'utiliser de telles anciennes pratiques obsolètes pour le balisage. Cependant, dans ce cas, il y a une bonne raison de faire une exception. L'outil JavaDoc (sauf s'il est radicalement mis à jour avec des Doclets personnalisés) génère un balisage ancien, cruel et quelque peu cassé. Les navigateurs ont été conçus pour être rétrocompatibles avec le vieux balisage fou de la journée, il est donc logique que vous l'acceptiez. Votre utilisation de <P> pour séparer les paragraphes sera en ligne avec le reste de la sortie JavaDoc.
À proprement parler, une fermeture automatique <p /> n'a aucun sens, car <p> doit être utilisé pour contenir un paragraphe, c'est-à-dire que le paragraphe doit être entouré par <p> et </p>.
<br> est cependant une balise de "niveau inférieur" qui indique un saut de ligne. Ainsi, la façon sémantiquement correcte d'indiquer les paragraphes serait d'utiliser <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> entraîne plus d'espace entre les lignes, tandis qu'un <br> commencera simplement une nouvelle ligne et n'introduira aucun espace blanc majeur.
Avec Java 8, un seul élément de départ (<p>) travaux.
Notez que javadoc n'aime pas l'élément de fermeture (</p>).