Erweitern Inline-Tags in benutzerdefinierten Javadoc taglet

Question

Ich schrieb eine benutzerdefinierte Javadoc taglet, die einen neuen note Tag fügt hinzu:

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

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

Es funktioniert so weit, aber Inline-Tags werden nicht erweitert. Hier ist ein Beispiel Kommentar:

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

Der {@link} Inline-Tag wird nicht erweitert. Es ist jedoch gut für die eingebaute in param javadoc Tag arbeitet.

Gibt es eine Möglichkeit verschachtelte Inline-Tags in einem benutzerdefinierten Javadoc taglet zu erweitern?

Danke!

Answer 1

Die Taglet Überblick sagt :

Taglets kann entweder als Block-Tags geschrieben werden, wie @todo oder Inline-Tags wie {@underline}. Block Taglets derzeit nicht Inline-Tags in ihrem Text unterstützen.

In der Tat, die taglet API ist ein bisschen zu minimal, da er nur die toString() Methode unterstützt.

Sie können innerhalb dieses Verfahren die Unter-Tags des Parameters tag abrufen (mit .inlineTags()), aber dann würden Sie haben sie selbst zu formatieren, da Sie Zugriff auf den normalen Maschinen der Standard doclet nicht von Ihrem taglet haben.

So, sieht aus wie Sie sind aus Glück hier, wenn Sie nicht wollen, neu zu implementieren (oder Kopie) Teile der Norm doclet in Ihrem eigenen taglet. (Aber dann könnte man das gleiche direkt den Standard doclet erweitern, anstatt sie mit Taglets Patchen.)

Answer 2

Hier drei mögliche Ideen, von denen keines Ich mag:

1. Statt der eigenen Taglet definieren, verwenden Sie die -tag Option zum javadoc Befehl Unterstützung @note. Natürlich wird dies nicht zulassen, definieren Sie Ihre eigene benutzerdefinierte Formatierung.

2. Sie könnten tag.holder().setRawCommentText(String) verwenden. Meine Erfahrung spielt dabei ist, dass auf diese Weise können Sie Tags hinzufügen, aber Sie nicht läßt einen Tag neu schreiben. So können Sie einen String Ersatz auf tag.holder().getRawCommentText() nicht tun und dann die Standard-doclet die Inline-Tags richtig machen, aber Sie könnten wahrscheinlich Ihre Taglet.toString(Tag[]) Methode, um die HTML zu erzeugen, einschließlich der Rohform der Inline-Tags, und dann Anfügen auf das rohe Kommentartext "@renderedNote markedUp Tag.text () ", wo @renderedNote anderer Tag ist, mit -tag definiert. Ihre Taglet.toString(Tag[]) sollte dann eine leere Zeichenfolge zurück. Doch nicht nur das ist hässlich, ich weiß nicht, ob dies auf undokumentierte Verhalten beruht und so weiß ich nicht, wie robust oder zukunftssicher ist diese Idee.

3. könnten Sie haben Ihre Taglet auch com.sun.tools.doclets.internal.toolkit.taglets.Taglet implementieren. Dies scheint zu sein, wie die Standard-Taglets definiert. Die beiden Methoden, die Sie dann umsetzen müssen sind TagletOutput getTagletOutput(Tag tag, TagletWriter writer) und TagletOutput getTagletOutput(Doc doc, TagletWriter writer). Ich denke, letzteres nur throw IllegalArgumentException(). Wenn Sie auch die Map halten zur Verfügung gestellt, wenn Ihr Taglet registriert wurde, dann können Sie in der Lage sein, mehrere der Inline-Tags zu machen, dass Sie durch Nachschlagen des Tag-Namen in diesem Map zu bekommen ihre Umsetzung com.sun.tools.doclets.internal.toolkit.taglets.Taglet und Delegieren von seiner getTagletOutput Methode begegnen. Allerdings sieht es aus wie zum Beispiel @link-Tags nicht in dieser Karte eingetragen sind; für diejenigen, ist es möglich (aber ich habe nicht überprüft), dass, weil @link Tags angeblich als SeeTag vorgesehen sind Sie in der Lage sein, die Karte von @see zu verwenden, anstatt, oder man kann den TagletWriter zu TagletWriterImpl gegossen und dann TagletWriterImpl.seeTagOutput(Doc, SeeTag[]) verwenden. Für Text-Tags können Sie TagletOutput Instanzen über new TagletOutputImpl(String) erzeugen. Schließlich alle TagletOutput Fällen, dass Sie auf diese Weise erhalten können in einem einzigen TagletOutput kombiniert werden TagletOutput.append(TagletOutput) werden zurückgegeben werden.