在自定义 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 概述说：

Taglet 可以写成块标签（例如@todo）或内联标签（例如{@underline}）。块 taglet 目前不支持其文本中的内联标记。

事实上，taglet API 有点太小了，因为它只支持 toString() 方法。

您可以在此方法中检索参数 tag 的子标签（使用 .inlineTags()），但是您必须自己格式化它们，因为您没有从 taglet 访问标准 doclet 的正常机制。

因此，如果您不想在自己的 taglet 中重新实现（或复制）标准 doclet 的部分内容，那么看起来您运气不好。 （但是，您同样可以直接扩展标准 doclet，而不是用 taglet 修补它。）

Answer 2

这里有三个可能的想法，但我并不真正喜欢其中一个：

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

2. 您可以使用tag.holder().setRawCommentText(String)。我的经验是，这可以让您添加标签，但不允许您重写标签。因此，您无法对 tag.holder().getRawCommentText() 进行字符串替换，然后让标准 doclet 正确渲染内联标记，但您可能可以使用 Taglet.toString (Tag[]) 方法生成 html，包括原始形式的内联标签，然后附加到原始注释文本“@renderedNote markedUp Tag.text() ”，其中 @renderedNote 是另一个标签，使用 -tag 定义。然后，您的 Taglet.toString(Tag[]) 应返回一个空字符串。然而，这不仅丑陋，我不知道这是否依赖于未记录的行为，所以我不知道这个想法有多稳健或未来的证明。

3. 您可以让您的 Taglet 也实现 com.sun.tools.doclets.internal.toolkit.taglets.Taglet。这似乎就是标准 taglet 的定义方式。您必须实现的两个方法是 TagletOutput getTagletOutput(Tag tag, TagletWriter writer) 和 TagletOutput getTagletOutput(Doc doc, TagletWriter writer)。我认为后者可以抛出 IllegalArgumentException()。如果您还保留注册 Taglet 时提供的 Map，那么您可以通过在其中查找标记名称来呈现您遇到的多个内联标记。 Map 获取其实现 com.sun.tools.doclets.internal.toolkit.taglets.Taglet 并委托给其 getTagletOutput 方法。但是，例如，@link 标签似乎未在该地图中注册；对于这些，有可能（但我没有检查过），因为 @link 标签据称是作为 SeeTag 提供的，您也许可以使用 @ 中的地图see 相反，或者您可以将 TagletWriter 转换为 TagletWriterImpl，然后使用 TagletWriterImpl.seeTagOutput(Doc, SeeTag[])。对于 Text 标签，您可以通过 new TagletOutputImpl(String) 生成 TagletOutput 实例。最后，通过这种方式获得的所有 TagletOutput 实例都可以组合成一个 TagletOutput，并使用 TagletOutput.append(TagletOutput) 返回。< /p>