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

score 27 · Accepted Answer · answered Sep 15 '11 at 08:41

27

java code

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

java doc option

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

output

This is my Tag:

hey ho...

answered Sep 15 '11 at 08:41

appsthatmatter

6,347
3
36
40

1

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. – prime Aug 14 '17 at 15:44
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'. – Trunk Nov 25 '18 at 13:53

knownasilya · Answer 2 · 2012-10-22T20:25:05.677

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:

Third configuration screen for Eclipse Doclet Javadoc Export

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

You argument about changing HTML is invalid. Check official taglet example on Oracle [site](http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/taglet/overview.html) they use HTML without any preconditions... — Serhiy, Jun 24 '15 at 21:16
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. — prime, Aug 14 '17 at 15:45
Basically, it's a namespace, so you don't clash with built in tags. — knownasilya, Aug 16 '17 at 18:47
I know it's just an example, but HTML can be embedded in markdown. It's how Jekyll works. — Pranav A., Feb 12 '18 at 23:21

score 0 · Answer 3 · edited Jan 09 '16 at 04:37

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!

score 0 · Answer 4 · answered Mar 11 '17 at 02:49

0

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

answered Mar 11 '17 at 02:49

trevren11

192
1
4
10

How to create custom javadoc tags?

4 Answers4

Linked