Ampliar etiquetas en línea en taglet Javadoc personalizada

Question

Me escribió una taglet Javadoc a medida que añade una nueva etiqueta note:

 ...
 public boolean isInlineTag() { return false; }

  public String toString(Tag tag) {
      return "<pre class='note'>" + tag.text() + "</pre>";
   }

Se trabaja hasta ahora, pero etiquetas en línea no se expanden. He aquí un comentario ejemplo:

/**
 * @note Test note with {@link Someclass} // @link tag is NOT expanded
 * @param name - here the {@link Someclass} works // works for standard 'param' tag
 */

La etiqueta {@link} en línea no se expande. Sin embargo, funciona muy bien para el incorporado en la etiqueta param javadoc.

¿Hay una manera de ampliar etiquetas en línea anidados en un taglet Javadoc personalizada?

Gracias!

Answer 1

El Taglet visión general dice :

Taglets se puede escribir ya sea como etiquetas de bloque, como @todo, o etiquetas en línea, tales como {} @underline. Bloque taglets no admiten etiquetas en línea en su texto.

De hecho, el API taglet es un poco demasiado mínimo, ya que sólo es compatible con el método toString().

Se podría dentro de este método de recuperar las etiquetas secundarias del tag parámetro (con .inlineTags()), pero entonces tendría que dar formato a su propia cuenta, ya que no tiene acceso a la maquinaria normal de la doclet estándar de su taglet.

Por lo tanto, parece que estás de suerte aquí, si no desea volver a implementar (o copia) partes del doclet estándar en su propio taglet. (Pero entonces, se podría extender la misma directamente a la doclet estándar en lugar de aplicación de parches con taglets.)

Answer 2

Aquí hay tres ideas posibles, ninguno de los cuales me gusta mucho:

1. En lugar de definir su propio Taglet, utilice la opción -tag al comando javadoc a @note apoyo. Por supuesto, esto no le permitirá definir el formato de su propia medida.

2. Se puede usar tag.holder().setRawCommentText(String). Mi experiencia de juego con esto es que esto le permite añadir etiquetas, pero no le permite volver a escribir una etiqueta. Así que no se puede hacer un reemplazo cadena en tag.holder().getRawCommentText() y luego tener la norma doclet hacen las etiquetas en línea correctamente, pero es probable que podría tener su método Taglet.toString(Tag[]) generar el HTML, incluyendo la forma cruda de las etiquetas en línea y, a continuación, anexados a la prima comentario de texto "@renderedNote markedUp Tag.text () " donde @renderedNote es otra etiqueta, que se define utilizando -tag. Su Taglet.toString(Tag[]) debe entonces devolver una cadena vacía. Sin embargo, no sólo es feo, no sé si esto se basa en el comportamiento indocumentado y por lo tanto no sé cuán robustos o prueba de futuro de esta idea es.

3. Usted podría tener su Taglet también implementar com.sun.tools.doclets.internal.toolkit.taglets.Taglet. Esto parece ser cómo se definen los taglets estándar. Los dos métodos que se tiene que aplicar son TagletOutput getTagletOutput(Tag tag, TagletWriter writer) y TagletOutput getTagletOutput(Doc doc, TagletWriter writer). Creo que el último puede simplemente throw IllegalArgumentException(). Si también mantiene el Map proporcionó cuando se registró su Taglet, entonces usted puede ser capaz de hacer varias de las etiquetas en línea que usted encuentra buscando el nombre de la etiqueta en la que Map para obtener su com.sun.tools.doclets.internal.toolkit.taglets.Taglet implementación y delegar a su método getTagletOutput. Sin embargo, parece que, por ejemplo, etiquetas @link no están registrados en ese mapa; para aquellos, es posible (pero no lo he comprobado) que debido a que las etiquetas se @link supuestamente proporcionan como SeeTag es posible que pueda usar el mapa de @see vez, o se puede emitir el TagletWriter a TagletWriterImpl y luego usar TagletWriterImpl.seeTagOutput(Doc, SeeTag[]). Para las etiquetas Text, puede generar instancias TagletOutput través new TagletOutputImpl(String). Finalmente todos los casos TagletOutput que se obtiene de esta manera se pueden combinar en una sola TagletOutput que ser devueltos usando TagletOutput.append(TagletOutput).