How to create custom javadoc tags?

Question

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:

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

Answer 1

java code

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

java doc option

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

output

This is my Tag:

hey ho...

Answer 2

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 Markdown in the future, also the Javadoc exporter will not catch missing information and you might have empty "tags".

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.

Comment from doclet.

Custom tags that could override future standard tags: @wrapper To avoid potential overrides, use at least one period character (.) in custom tag names.

---

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

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.

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

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