Expand inline tags in custom Javadoc taglet

Question

I wrote a custom Javadoc taglet that adds a new note tag:

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

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

It works so far, but inline tags are not expanded. Here is an example comment:

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

The {@link} inline tag is not expanded. However, it works just fine for the built-in param javadoc tag.

Is there a way to expand nested inline tags in a custom Javadoc taglet?

Thanks!

Answer 1

The Taglet overview says:

Taglets can be written as either block tags, such as @todo, or inline tags, such as {@underline}. Block taglets do not currently support inline tags in their text.

In fact, the taglet API is a bit too minimal, as it supports only the toString() method.

You could inside this method retrieve the subtags of the parameter tag (with .inlineTags()), but then you would have to format them yourself, since you don't have access to the normal machinery of the standard doclet from your taglet.

So, looks like you are out of luck here, if you don't want to reimplement (or copy) parts of the standard doclet in your own taglet. (But then, you could the same directly extend the standard doclet instead of patching it with taglets.)

Answer 2

Here's three possible ideas, none of which I really like:

1. Instead of defining your own Taglet, use the -tag option to the javadoc command to support @note. Of course, this won't let you define your own custom formatting.

2. You could use tag.holder().setRawCommentText(String). My experience playing with this is that this lets you add tags, but doesn't let you rewrite a tag. So you can't do a string replacement on tag.holder().getRawCommentText() and then have the standard doclet render the inline tags properly, but you could probably have your Taglet.toString(Tag[]) method generate the html, including the raw form of the inline tags, and then append to the raw comment text "@renderedNote markedUp Tag.text()" where @renderedNote is another tag, defined using -tag. Your Taglet.toString(Tag[]) should then return an empty string. However, not only is this ugly, I don't know if this relies on undocumented behavior and so I don't know how robust or future proof this idea is.

3. You could have your Taglet also implement com.sun.tools.doclets.internal.toolkit.taglets.Taglet. This seems to be how the standard taglets are defined. The two methods you then have to implement are TagletOutput getTagletOutput(Tag tag, TagletWriter writer) and TagletOutput getTagletOutput(Doc doc, TagletWriter writer). I think the latter can just throw IllegalArgumentException(). If you also keep the Map provided when your Taglet was registered, then you may be able to render several of the inline tags that you encounter by looking up the tag name in that Map to get its implementing com.sun.tools.doclets.internal.toolkit.taglets.Taglet and delegating to its getTagletOutput method. However, it looks like, for example, @link tags are not registered in that map; for those, it's possible (but I haven't checked) that because @link tags are supposedly provided as SeeTag you may be able to use the map from @see instead, or you could cast the TagletWriter to TagletWriterImpl and then use TagletWriterImpl.seeTagOutput(Doc, SeeTag[]). For Text tags, you can generate TagletOutput instances via new TagletOutputImpl(String). Finally all the TagletOutput instances that you get this way can be combined into a single TagletOutput to be returned using TagletOutput.append(TagletOutput).