在自定义Javadoc Taglet中展开内联标签

Question

我写了一个自定义的Javadoc Taglet，添加了一个新的 note 标签：

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

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

到目前为止，它可以正常工作，但是内联标签没有扩展。这是一个示例评论：

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

这 {@link} 内联标签没有扩展。但是，它可以很好地适合内置 param Javadoc标签。

有没有一种方法可以在自定义的Javadoc taglet中扩展嵌套的内联标签？

谢谢！

Answer 1

这 taglet概述 说：

taglets可以写为块标签，例如@todo或inline标签，例如{@underline}。 Block Taglet当前不支持其文本中的内联标签。

实际上，taglet API太小了，因为它仅支持 toString() 方法。

您可以在此方法内检索参数的子标签 tag （和 .inlineTags()），但是您必须自己格式化它们，因为您无法从taglet中访问标准Doclet的普通机械。

因此，如果您不想在自己的taglet中重新进化（或复制）部分，那么您似乎在这里不幸。 （但是，您可以直接扩展标准Doclet，而不是用Taglet进行修补。）

Answer 2

这是三个可能的想法，我都不喜欢：

1. 而不是定义自己的 Taglet, ， 使用 -tag 选项 javadoc 命令支持 @note. 。当然，这不会让您定义自己的自定义格式。

2. 您可以使用 tag.holder().setRawCommentText(String). 。我对此进行的经验是，这使您可以添加标签，但不允许您重写标签。因此，您不能在上面替换字符串 tag.holder().getRawCommentText() 然后使标准Doclet正确渲染内联标签，但是您可能会拥有您的 Taglet.toString(Tag[]) 方法生成HTML，包括内联标签的原始形式，然后附加到原始注释文本”@renderedNote 标记tag.text（）“ 在哪里 @renderedNote 是另一个标签，使用 -tag. 。您的 Taglet.toString(Tag[]) 然后应该返回一个空字符串。但是，这不仅是丑陋的，我不知道这是否依赖于无证件的行为，因此我不知道这个想法是多么健壮或将来的证明。

3. 你可以有你的 Taglet 也实施 com.sun.tools.doclets.internal.toolkit.taglets.Taglet. 。这似乎是标准标签的定义方式。然后，您必须实现的两种方法是 TagletOutput getTagletOutput(Tag tag, TagletWriter writer) 和 TagletOutput getTagletOutput(Doc doc, TagletWriter writer). 。我认为后者可以 throw IllegalArgumentException(). 。如果您还保留 Map 提供时提供 Taglet 已注册，然后您可以通过查找该标签名称来渲染遇到的几个内联标签 Map 获得其实施 com.sun.tools.doclets.internal.toolkit.taglets.Taglet 并委派 getTagletOutput 方法。但是，看起来，例如 @link 标签未在该地图中注册；对于这些，有可能（但我尚未检查），因为 @link 标签被认为是 SeeTag 您可能可以使用地图 @see 相反，或者您可以施放 TagletWriter 至 TagletWriterImpl 然后使用 TagletWriterImpl.seeTagOutput(Doc, SeeTag[]). 。为了 Text 标签，您可以生成 TagletOutput 实例通过 new TagletOutputImpl(String). 。最后所有 TagletOutput 您以这种方式获得的实例可以合并为一个 TagletOutput 返回使用 TagletOutput.append(TagletOutput).