javadoc custom tags

Question

I've been googling for almost an hour and I can't find any good information on making custom tags. When I check the help for javadoc is says this about custom tags...

-tag < name >:< locations >:< header >

It does not define what any of things are. I think name would be the name of the tag and header is probably what the tag says when you generate the javadoc but what is locations and how is it used?

Also does the name, locations, and header need to be in quotes or anything like that?

A few examples of custom tags and maybe an explanation of what locations is would be a HUGE help for me. I can't find any good tutorials on this specific part of making a javadoc...

Answer 1

Looks you have only invoked javadoc -help. This is only a short reminder about the options, not a complete documentation.

In principle, everything is explained in detail on the javadoc documentation page (for Windows and Linux/Solaris).

The -tag option is for adding custom tags to the standard doclet without having to create an own taglet (there you would use the -taglet option) or even an own doclet.

All the parameters to the option have to be one command line argument, so depending on your shell you usually have to put them (together or individually) in quotes if they contain any spaces.

-tag tagname:Xaoptcmf:"taghead"

• The tagname is the name of your custom tag - for example, if you are writing @todo in the source, the name would be todo.
• The middle parameter is an identifier for the locations where this tag is allowed. This can be a combination of a (everywhere), o (only in the overview page), p (on package documentation), t (for class or interface documentation), c (for constructors), m (for methods), f (for fields). Additionally there can be an X meaning the tag is accepted but no output shown. (Then you don't need the taghead part).
• The taghead is what should be shown in the generated source as the header for your tag, for example To Do: for our todo-tag.

So, if you @todo tag should be allowed everywhere and print To Do:, you would use

-tag todo:a:"To Do:"