Etiquetas HTML permitidas en Javadoc

checkstyle

Question

La regla de JavadocStyle verificación JavadocStyle no permite la etiqueta <u> . De acuerdo con los documentos, los controles se ajustaron a los patrones realizados por el doclet DocCheck disponible de Sun. Desafortunadamente, no he encontrado DocCheck en ninguna parte. Tampoco he encontrado ninguna documentación oficial sobre las etiquetas HTML permitidas en Javadoc. ¿Hay alguna?

Answer 1

Javadoc solo permite un subconjunto de etiquetas HTML, a partir de Java 8.

El componente doclint de Javadoc impone esta restricción. Puede deshabilitar todas las advertencias de -Xdoclint:none pasando -Xdoclint:none a javadoc, aunque debería considerar corregir sus comentarios de Javadoc porque, de lo contrario, la documentación de la API HTML generada puede verse mal o puede omitir el contenido. (Por lo general, uso -Xdoclint:all,-missing para obtener advertencias sobre todo excepto las etiquetas Javadoc @ faltan).

No he encontrado documentación pública de las etiquetas que doclint permite, pero aquí hay una lista de sus etiquetas HTML permitidas, que obtuve del archivo 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

Actualización para JDK 9

JDK 9 permite un conjunto diferente de etiquetas que JDK 8. Aquí hay una lista de etiquetas para ambos JDK, con notas sobre aquellas permitidas por solo uno de los JDK. Una vez más, los datos provienen del archivo HTMLTag.java .

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

No hay restricciones reales en el uso de HTML en los comentarios de Javadoc. La documentación de Javadoc establece:

Los comentarios están escritos en HTML: el texto debe estar escrito en HTML, en el sentido de que deben usar entidades HTML y pueden usar etiquetas HTML. Puedes usar cualquier versión de HTML que admita tu navegador; hemos escrito el doclet estándar para generar código compatible con HTML 3.2 en otro lugar (fuera de los comentarios de la documentación) con la inclusión de hojas de estilo y marcos en cascada. (Prologamos cada archivo generado con "HTML 4.0" debido a los conjuntos de marcos.)

La lista de etiquetas HTML permitidas está codificada en la JavadocStyle comprobación de JavadocStyle (verificada en las fuentes de verificación de estilo 5.6). Entonces, si desea mantener la verificación de sus otras buenas propiedades, tendrá que vivir con el conjunto restringido de etiquetas HTML. Una solución para el problema de subrayado es usar CSS (que está permitido) de la siguiente manera:

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