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

Chasechaser

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

Brookins

Any specific reason to use custom.mytag ? What will happen when there is a dot, can we read and separate those names or something , or is it just to clearly state the name. – Poplin

If it operates as done elsewhere in coding, a dot signifies that what comes after it is a member of the type-collection entity before the dot. This allows all custom tags to be handled via a procedure established for the type-collection 'custom'. – Villager

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

Bayberry

You argument about changing HTML is invalid. Check official taglet example on Oracle site they use HTML without any preconditions... – Emeryemesis

Any specific reason to use tt.wrapper ? What will happen when there is a dot, can we read and separate those names or something , or is it just to clearly state the name. – Poplin

Basically, it's a namespace, so you don't clash with built in tags. – Bayberry

I know it's just an example, but HTML can be embedded in markdown. It's how Jekyll works. – Manheim

Answer 3

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!

Chasechaser

Answer 4

If you want multiple, do something like javadoc -tag pre -tag post -tag invariant where it asks for command line arguments. Don't use the html stuff

Totalitarian