Espandere i tag in linea in Javadoc taglet personalizzato
-
10-10-2019 - |
Domanda
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!
Soluzione
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.)
Altri suggerimenti
Ecco tre idee possibili, nessuno dei quali mi piace molto:
-
Invece di definire il proprio
Taglet
, utilizzare l'opzione-tag
al comandojavadoc
al supporto@note
. Naturalmente, questo non ti consente di definire la formattazione il proprio personalizzato. -
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 sutag.holder().getRawCommentText()
e quindi avere la doclet standard di rendere i tag in linea correttamente, ma probabilmente si potrebbe avere il tuo metodoTaglet.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 tuoTaglet.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 è. -
Si potrebbe avere il vostro
Taglet
anche implementarecom.sun.tools.doclets.internal.toolkit.taglets.Taglet
. Questo sembra essere come i taglets standard sono definiti. I due metodi è quindi necessario implementare sonoTagletOutput getTagletOutput(Tag tag, TagletWriter writer)
eTagletOutput getTagletOutput(Doc doc, TagletWriter writer)
. Credo che quest'ultimo può solothrow IllegalArgumentException()
. Se si mantiene anche laMap
fornito quando ilTaglet
è stato registrato, allora si può essere in grado di rendere alcuni dei tag in linea che si incontrano, cercando il nome del tag in quelMap
per ottenere la suacom.sun.tools.doclets.internal.toolkit.taglets.Taglet
attuazione e delegando al suo metodogetTagletOutput
. 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 comeSeeTag
si può essere in grado di utilizzare la mappa da@see
invece, o si potrebbe lanciare ilTagletWriter
perTagletWriterImpl
e quindi utilizzareTagletWriterImpl.seeTagOutput(Doc, SeeTag[])
. Per i tagText
, è possibile generare le istanzeTagletOutput
vianew TagletOutputImpl(String)
. Infine tutte le istanzeTagletOutput
che si ottiene in questo modo possono essere combinati in un unicoTagletOutput
da restituire usandoTagletOutput.append(TagletOutput)
.