Espandere i tag in linea in Javadoc taglet personalizzato

Question

ho scritto un taglet Javadoc personalizzato che aggiunge un nuovo tag note:

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

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

Funziona così lontano, ma i tag non ancorati non siano espanse. Ecco un esempio commento:

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

Il tag {@link} linea non è espansa. Tuttavia, funziona bene per il built-in tag param javadoc.

C'è un modo per espandere i tag annidati in linea in un taglet Javadoc personalizzato?

Grazie!

Answer 1

Il Taglet panoramica dice :

Taglets può essere scritto sia come tag di blocco, come @todo, o tag in linea, ad esempio {} @underline. Blocco taglets attualmente non supportano i tag in linea nel loro testo.

In realtà, l'API taglet è un po 'troppo minimale, in quanto supporta solo il metodo toString().

Si potrebbe all'interno di questo metodo di recuperare i sottotag del parametro tag (con .inlineTags()), ma poi si sarebbe dovuto formattare voi stessi, dal momento che non si ha accesso al normale macchina del doclet standard dal tuo taglet.

Quindi, sembra che si sta fuori di fortuna qui, se non si vuole reimplementare (o copiare) le parti del doclet standard nella vostra taglet. (Ma allora, si potrebbe estendere la stessa direttamente il doclet standard invece di patch con taglets.)

Answer 2

Ecco tre idee possibili, nessuno dei quali mi piace molto:

1. Invece di definire il proprio Taglet, utilizzare l'opzione -tag al comando javadoc al supporto @note. Naturalmente, questo non ti consente di definire la formattazione il proprio personalizzato.

2. Si potrebbe utilizzare tag.holder().setRawCommentText(String). La mia esperienza di gioco con questo è che questo consente di aggiungere i tag, ma non consente di riscrivere un tag. Così non si può fare una sostituzione stringa su tag.holder().getRawCommentText() e quindi avere la doclet standard di rendere i tag in linea correttamente, ma probabilmente si potrebbe avere il tuo metodo Taglet.toString(Tag[]) generare il codice HTML, compresa la forma grezza dei tag in linea, e quindi aggiungere al grezzo testo di commento "@renderedNote markedUp Tag.text () " dove @renderedNote è un altro tag, definito tramite -tag. Il tuo Taglet.toString(Tag[]) dovrebbe quindi restituire una stringa vuota. Tuttavia, non è solo questo brutto, non so se questo si basa su comportamenti privi di documenti e quindi non so come robusto o prova di futuro questa idea è.

3. Si potrebbe avere il vostro Taglet anche implementare com.sun.tools.doclets.internal.toolkit.taglets.Taglet. Questo sembra essere come i taglets standard sono definiti. I due metodi è quindi necessario implementare sono TagletOutput getTagletOutput(Tag tag, TagletWriter writer) e TagletOutput getTagletOutput(Doc doc, TagletWriter writer). Credo che quest'ultimo può solo throw IllegalArgumentException(). Se si mantiene anche la Map fornito quando il Taglet è stato registrato, allora si può essere in grado di rendere alcuni dei tag in linea che si incontrano, cercando il nome del tag in quel Map per ottenere la sua com.sun.tools.doclets.internal.toolkit.taglets.Taglet attuazione e delegando al suo metodo getTagletOutput. Tuttavia, sembra che, per esempio, i tag @link non sono registrati in quella mappa; per chi, è possibile (ma non ho controllato) che, poiché i tag @link sono presumibilmente forniti come SeeTag si può essere in grado di utilizzare la mappa da @see invece, o si potrebbe lanciare il TagletWriter per TagletWriterImpl e quindi utilizzare TagletWriterImpl.seeTagOutput(Doc, SeeTag[]). Per i tag Text, è possibile generare le istanze TagletOutput via new TagletOutputImpl(String). Infine tutte le istanze TagletOutput che si ottiene in questo modo possono essere combinati in un unico TagletOutput da restituire usando TagletOutput.append(TagletOutput).