Balises HTML autorisées dans la Javadoc

Question

La règle du Checkstyle JavadocStyle n'autorise pas la balise <u> . D'après la documentation, les vérifications sont calquées sur celles effectuées par le doclet DocCheck disponible chez Sun. Malheureusement, je n'ai trouvé DocCheck nulle part. Je n'ai pas non plus trouvé de documentation officielle sur les balises HTML autorisées dans Javadoc. En existe-t-il ?

Answer 1

Javadoc ne permet qu'un sous-ensemble de balises HTML, à partir de Java 8.

Le composant doclint de Javadoc applique cette restriction. Vous pouvez désactiver tous les avertissements de doclint en passant le paramètre -Xdoclint:none à la javadoc, mais vous devriez envisager de corriger vos commentaires Javadoc, car sinon la documentation HTML de l'API générée peut avoir une mauvaise apparence ou omettre du contenu. (J'utilise généralement -Xdoclint:all,-missing pour obtenir des avertissements sur tout, sauf sur les Javadoc manquantes. @ tags).

Je n'ai pas trouvé de documentation publique sur les balises que doclint autorise, mais voici une liste de ses balises HTML autorisées, que j'ai glanée dans le fichier de Java 8 langtools/src/share/classes/com/sun/tools/doclint/HtmlTag.java .

A
B
BIG
BLOCKQUOTE
BODY
BR
CAPTION
CENTER
CITE
CODE
DD
DFN
DIV
DL
DT
EM
FONT
FRAME
FRAMESET
H1
H2
H3
H4
H5
H6
HEAD
HR
HTML
I
IMG
LI
LINK
MENU
META
NOFRAMES
NOSCRIPT
OL
P
PRE
SCRIPT
SMALL
SPAN
STRONG
SUB
SUP
TABLE
TBODY
TD
TFOOT
TH
THEAD
TITLE
TR
TT
U
UL
VAR

Mise à jour pour JDK 9

Le JDK 9 autorise un ensemble de balises différent de celui du JDK 8. Voici une liste de balises pour les deux JDK, avec des notes sur celles qui ne sont autorisées que par l'un des JDK. Encore une fois, les données proviennent de la base de données HTMLTag.java fichier.

A
BIG       // JDK 8 only
B         // JDK 8 only
BLOCKQUOTE
BODY
BR
CAPTION
CENTER
CITE      // JDK 8 only
CODE
DD
DFN       // JDK 8 only
DIR       // JDK 9 only
DIV
DL
DT
EM
FONT
FOOTER    // JDK 9 only
FRAME     // JDK 8 only
FRAMESET  // JDK 8 only
H1
H2
H3
H4
H5
H6
HEAD
HEADER     // JDK 9 only
HR
HTML
I
IFRAME     // JDK 9 only
IMG
INPUT      // JDK 9 only
LI
LINK
LISTING    // JDK 9 only
MAIN       // JDK 9 only
MENU
META
NAV        // JDK 9 only
NOFRAMES   // JDK 8 only
NOSCRIPT
OL
P
PRE
SCRIPT
SECTION     // JDK 9 only
SMALL
SPAN
STRONG
SUB
SUP         // JDK 8 only
TABLE
TBODY
TD
TFOOT       // JDK 8 only
TH
THEAD       // JDK 8 only
TITLE
TR
TT
U           // JDK 8 only
UL
VAR         // JDK 8 only

Answer 2

Il n'y a pas de réelles restrictions sur l'utilisation du HTML dans les commentaires de Javadoc. Le site Documentation Javadoc États :

Les commentaires sont écrits en HTML - Le texte doit être écrit en HTML, c'est-à-dire qu'il doit utiliser des entités HTML et peut utiliser des balises HTML. Vous pouvez utiliser la version de HTML que votre navigateur prend en charge ; nous avons écrit le doclet standard pour générer du code conforme à HTML 3.2 ailleurs (en dehors des commentaires de la documentation) avec l'inclusion de feuilles de style en cascade et de cadres. (Nous faisons précéder chaque fichier généré de la mention "HTML 4.0" en raison des jeux de cadres).

La liste des balises HTML autorisées est codée en dur dans le fichier JavadocStyle Checkstyle (vérifié en regardant les sources de Checkstyle 5.6). Donc, si vous voulez conserver le contrôle pour ses autres bonnes propriétés, vous devrez vivre avec un ensemble restreint de balises HTML. Une solution de contournement pour le problème du soulignement est d'utiliser le CSS (qui est autorisé) comme ceci :

<span style="text-decoration:underline;">underlined text</span>