Expand inline tags in custom Javadoc taglet
I wrote a custom Javadoc taglet that adds开发者_C百科 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!
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.)
Here's three possible ideas, none of which I really like:
Instead of defining your own
Taglet
, use the-tag
option to thejavadoc
command to support@note
. Of course, this won't let you define your own custom formatting.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 ontag.holder().getRawCommentText()
and then have the standard doclet render the inline tags properly, but you could probably have yourTaglet.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
. YourTaglet.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.You could have your
Taglet
also implementcom.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 areTagletOutput getTagletOutput(Tag tag, TagletWriter writer)
andTagletOutput getTagletOutput(Doc doc, TagletWriter writer)
. I think the latter can justthrow IllegalArgumentException()
. If you also keep theMap
provided when yourTaglet
was registered, then you may be able to render several of the inline tags that you encounter by looking up the tag name in thatMap
to get its implementingcom.sun.tools.doclets.internal.toolkit.taglets.Taglet
and delegating to itsgetTagletOutput
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 asSeeTag
you may be able to use the map from@see
instead, or you could cast theTagletWriter
toTagletWriterImpl
and then useTagletWriterImpl.seeTagOutput(Doc, SeeTag[])
. ForText
tags, you can generateTagletOutput
instances vianew TagletOutputImpl(String)
. Finally all theTagletOutput
instances that you get this way can be combined into a singleTagletOutput
to be returned usingTagletOutput.append(TagletOutput)
.
精彩评论