如何创建自定义 javadoc 标签？答案

【问题标题】：How to create custom javadoc tags?如何创建自定义 javadoc 标签？
【发布时间】：2011-02-10 06:39:44
【问题描述】：

如何创建自定义 javadoc 标签，例如 @pre / @post？我找到了一些解释它的链接，但我没有运气。这些是一些链接：

http://www.developer.com/java/other/article.php/3085991/Javadoc-Programming.html

http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html

【问题讨论】：

【解决方案1】：

java 代码

/**
 * @custom.mytag hey ho...
 */

java 文档选项

-tag custom.mytag:a:"This is my Tag:"

输出

这是我的标签：

嘿嘿...

【讨论】：

使用custom.mytag的任何具体原因？当有dot时会发生什么，我们可以读取并分隔那些名称或其他东西，还是只是为了清楚地说明名称。
如果它像在编码中的其他地方一样操作，点表示它之后的内容是点之前的类型集合实体的成员。这允许通过为类型集合“自定义”建立的过程来处理所有自定义标签。

【解决方案2】：

不应使用 HTML 创建自定义标签，因为 javadoc 可能会更改它的实现或它呈现数据的方式，也许他们将来会开始使用 Markdown，Javadoc 导出器也不会捕获丢失的信息，你可能有空“标签”。

首先使用你想要的任何标签：

/**
 * Comments and a {@link #methodLink} for this method.
 * 
 * @tt.wrapper {@link OtherClass}
 *
 */
public String extractName() {
    // method contents
}

请注意，自定义标签的格式为@[prefix].[tagName]，这是因为 doclet（或其他 Eclipse 插件）可能会发布它自己的同名标签，而您的标签只会覆盖标准标签，所以我们添加一个前缀以降低发生这种情况的可能性。

来自 doclet 的评论。

可能覆盖未来标准标签的自定义标签：@wrapper 为避免潜在的覆盖，请在自定义标签名称中使用至少一个句点字符 (.)。

现在您必须将这个自定义标签@tt.wrapper 告诉Javadoc 导出器。在 Eclipse 中转到 Project > Generate Javadoc..（在我的例子中是 Indigo）。

配置此对话框的前两个屏幕的设置后（使用“下一步”更改屏幕），您应该会看到以下屏幕：

您应该注意到“Extra Javadoc options..”文本框具有您必须添加的值供 Javadoc 导出器创建与您的标签等效的 HTML。

在我们的例子中，选项是这样的（如果你想要多个标签，把它们放在一个新的行上）：

-tag tt.wrapper:a:"API Wrapper:"

现在，当您导出 Javadoc 时（我还建议保存一个 ANT 脚本，这样您就不必每次都通过此对话框）您的自定义标签会以粗体显示，并带有描述和下面的值。

附：我还没有找到一种方法来添加为自定义标签添加自动完成功能，但在 Indigo 中似乎是不可能的，也许它会在未来的版本中出现（不确定 Juno 是否有它）。

【讨论】：

您关于更改 HTML 的论点无效。查看 Oracle site 上的官方 taglet 示例，他们使用 HTML 没有任何先决条件...
使用tt.wrapper的任何具体原因？当有dot时会发生什么，我们可以读取并分隔那些名称或其他东西，还是只是为了清楚地说明名称。
基本上，它是一个命名空间，所以你不会与内置标签发生冲突。
我知道这只是一个例子，但是 HTML 可以嵌入到 markdown 中。这就是 Jekyll 的工作原理。

【解决方案3】：

好吧，我所做的不是最好的解决方案，但可以阅读：

  /** <p><b>Pre:</b></p>  <Ul>True</Ul>
    * <p><b>Post:</b></p> <Ul>The x is pushed onto the top of the stack,
    *                       and the rest of the stack remains unchanged.</Ul>
    *
    * @param x              Indicates the current node
    */
   public void push(int x){
      ...
   }

在找到正确答案之前，希望对您有所帮助！

【讨论】：

【解决方案4】：

如果您想要多个，请执行javadoc -tag pre -tag post -tag invariant 之类的操作，它会要求提供命令行参数。不要使用 html 的东西

【讨论】：