展开自定义Javadoc标记中的内联标记

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

我编写了一个自定义的Javadoc标记,它添加了一个新的标记标记:

 ...
 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.

{@link}内联标记未展开。但是,它适用于内置的param javadoc标记。

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

有没有办法在自定义Javadoc标记中扩展嵌套内联标记?

Thanks!

2 个解决方案

#1

The Taglet overview says:

Taglet概述说:

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.

Taglet可以编写为块标记(如@todo)或内联标记(如{@underline})。块标记当前不支持其文本中的内联标记。

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

事实上,taglet API有点过于简单,因为它只支持toString()方法。

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.

您可以在此方法中检索参数标记的子标签(使用.inlineTags()),但是您必须自己格式化它们,因为您无法从标记中访问标准doclet的常规机制。

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.)

因此,如果您不想在自己的标记中重新实现(或复制)标准doclet的某些部分,那么看起来您运气不好。 (但是,您可以直接扩展标准doclet,而不是使用taglet修补它。)

#2

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

这里有三个可能的想法,我都不喜欢这些想法:

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.

不要定义自己的Taglet,而是使用javadoc命令的-tag选项来支持@note。当然,这不会让您定义自己的自定义格式。
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.

您可以使用tag.holder()。setRawCommentText(String)。我使用它的经验是,这可以让你添加标签,但不允许你重写标签。所以你不能在tag.holder()。getRawCommentText()上做一个字符串替换,然后让标准的doclet正确地渲染内联标签,但你可以让你的Taglet.toString(Tag [])方法生成html,包括内联标签的原始形式,然后附加到原始注释文本“@renderedNote markedUp Tag.text()”,其中@renderedNote是另一个标签,使用-tag定义。然后你的Taglet.toString(Tag [])应该返回一个空字符串。然而,这不仅是丑陋的,我不知道这是否依赖于无证件行为,所以我不知道这个想法有多么强大或未来证明。
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).

你可以让你的Taglet也实现com.sun.tools.doclets.internal.toolkit.taglets.Taglet。这似乎是标准taglet的定义方式。然后,您必须实现的两种方法是TagletOutput getTagletOutput(Tag标记,TagletWriter编写器)和TagletOutput getTagletOutput(Doc doc,TagletWriter编写器)。我认为后者只能抛出IllegalArgumentException()。如果您在注册Taglet时也保留了Map,那么您可以通过查找该Map中的标记名称来渲染您遇到的几个内联标记,以实现其实现com.sun.tools.doclets.internal .toolkit.taglets.Taglet并委托给它的getTagletOutput方法。但是,看起来,例如,@ link标签未在该地图中注册;对于那些,有可能(但我没有检查),因为@link标签应该以SeeTag的形式提供,你可以使用@see中的地图,或者你可以将TagletWriter转换为TagletWriterImpl,然后使用TagletWriterImpl.seeTagOutput (Doc,SeeTag [])。对于Text标记,您可以通过新的TagletOutputImpl(String)生成TagletOutput实例。最后,您通过这种方式获得的所有TagletOutput实例都可以组合成一个TagletOutput,以便使用TagletOutput.append(TagletOutput)返回。

#1