如何创建自定义 javadoc 标签？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/2677564/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
How to create custom javadoc tags?
提问by Carlos
How do I create custom javadoc tags such as @pre / @post? I found some links that explain it but I haven't had luck with them. These are some of the links:
如何创建自定义 javadoc 标签，例如 @pre / @post？我找到了一些解释它的链接，但我没有运气。这些是一些链接：
http://www.developer.com/java/other/article.php/3085991/Javadoc-Programming.html
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
http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html
采纳答案by appsthatmatter
java code
代码
/**
* @custom.mytag hey ho...
*/
java doc option
java文档选项
-tag custom.mytag:a:"This is my Tag:"
output
输出
This is my Tag:
hey ho...
这是我的标签：
嘿嘿...
回答by Carlos
Well what i did is not the best solution but is readable:
那么我所做的不是最好的解决方案，但可读：
/** <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){
...
}
Till a proper answer is found, hope it helps!
直到找到正确的答案，希望它有所帮助！
回答by knownasilya
Custom tags should not be created using HTML because javadoc might change it's implementation or how it presents data, maybe they'll start using Markdownin the future, also the Javadoc exporter will not catch missing information and you might have empty "tags".
不应该使用 HTML 创建自定义标签，因为 javadoc 可能会改变它的实现或它呈现数据的方式，也许他们将来会开始使用Markdown，而且 Javadoc 导出器不会捕获丢失的信息，并且您可能有空的“标签”。
First use whatever tag you want:
首先使用你想要的任何标签：
/**
* Comments and a {@link #methodLink} for this method.
*
* @tt.wrapper {@link OtherClass}
*
*/
public String extractName() {
// method contents
}
Notice that the custom tag has the format @[prefix].[tagName], this is due to the fact that doclet (or another Eclipse plugin) might release it's own tag with the same name, and your tag would just override the standard tag, so we add a prefix to make it less likely of that happening.
请注意，自定义标签的格式为@[prefix].[tagName]，这是因为 doclet（或其他 Eclipse 插件）可能会发布自己的同名标签，而您的标签只会覆盖标准标签，因此我们添加一个前缀来使发生这种情况的可能性较小。
Comment from doclet.
来自 doclet 的评论。
Custom tags that could override future standard tags: @wrapper To avoid potential overrides, use at least one period character (.) in custom tag names.
可以覆盖未来标准标签的自定义标签：@wrapper 为避免潜在的覆盖，在自定义标签名称中至少使用一个句点字符 (.)。
Now you have to tell the Javadoc exporter about this custom tag, @tt.wrapper.
Go to Project > Generate Javadoc..in Eclipse (Indigo in my case).
现在您必须将这个自定义标签告诉 Javadoc 导出器，@tt.wrapper. 转到Project > Generate Javadoc..Eclipse（在我的情况下为 Indigo）。
After configuring the settings for the first two screens of this dialog (using "Next" to change screens) you should see this screen:
配置此对话框前两个屏幕的设置后（使用“下一步”更改屏幕），您应该看到以下屏幕：
You should notice that the "Extra Javadoc options.." text box has the value you must add for the Javadoc exporter to create the HTML equivalent of your tag.
您应该注意到“Extra Javadoc options..”文本框具有您必须为 Javadoc 导出器添加的值，以创建与您的标记等效的 HTML。
In our case the option is this (if you want multiple tags, put them on a new line):
在我们的例子中，选项是这样的（如果你想要多个标签，把它们放在一个新行）：
-tag tt.wrapper:a:"API Wrapper:"
Now when you export your Javadoc (I also recommend saving an ANTscript so you don't have to go through this dialog every time) you will have your custom tag in bold with the description, and the values underneath.
现在，当您导出 Javadoc 时（我还建议保存一个ANT脚本，这样您就不必每次都浏览此对话框），您将拥有带有描述的粗体自定义标记以及下面的值。
P.S. I have yet to find a way to add the ability to add auto-completion for the custom tags, but it seems impossible in Indigo, maybe it'll be in future releases (not sure if Juno has it).
PS 我还没有找到一种方法来添加为自定义标签添加自动完成的功能，但在 Indigo 中似乎不可能，也许它会在未来的版本中出现（不确定 Juno 是否有）。
回答by trevren11
If you want multiple, do something like javadoc -tag pre -tag post -tag invariantwhere it asks for command line arguments. Don't use the html stuff
如果您想要多个，请执行类似于javadoc -tag pre -tag post -tag invariant要求命令行参数的操作。不要使用 html 的东西
