7

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

3 Answers 3

10

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:"
2

Paŭlo Ebermann is correct, but I would like to add that Oracle said:

Avoiding Conflicts - If you want to slice out your own namespace, you can use a dot-separated naming convention similar to that used for packages: com.mycompany.todo. Sun will continue to create standard tags whose names do not contain dots. Any tag you create will override the behavior of a tag by the same name defined by Sun. In other words, if you create a tag or taglet @todo, it will always have the same behavior you define, even if Sun later creates a standard tag of the same name

http://docs.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html#tag

Which means that you shouldn't use @todo, you should use @to.do

More info here.

1

You can write custom Taglets and hook them into Javadoc relatively easily - there's a document explaining how here. Note that you need to specify the full absolute path to the location of the taglet, but that can be done relatively easily in ant.

Taglets are more time consuming than using the tag command, but they offer much more flexibility since you're essentially executing whatever Java code you choose - this way you can process or display any information as you like.

0

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.