javajava-8javadoctaglet

JDK 1.7 allows custom taglets with names *starting* with a dot. JDK 1.8 forbids it?

I've written a custom taglet library with names that start with a dot: .codelet, .codelet.and.out, etcetera. It is compiled with JDK 7.

When generating JavaDoc using the 1.7 javadoc.exe, it works fine. But when generating it with JDK 8, it fails because

C:\...\Temp.java:5: error: no tag name after @
 * {@.codelet mypkg.Temp}`

If I change the code using the taglet (not the taglet code itself) to {@codelet mypkg.Temp}:

C:\...\Temp.java:5: error: unknown tag: codelet
 * {@codelet mypkg.Temp}
Note: Custom tags that were not seen:  @.codelet
1 error

Changing the name in the taglet source code to be cod.elet (code.let is not good because code is an already existing taglet name), and using that new name, it works.

The JavaDoc tool documentation for the -tag option (near the bottom of the section) states:

Avoiding conflicts: If you want to create your own namespace, then you can use a dot-separated naming convention similar to that used for packages: com.mycompany.todo. Oracle 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 Oracle. If you create a @todo tag or taglet, then it always has the same behavior you define, even when Oracle later creates a standard tag of the same name.

So am I missing something here? Or it this an undocumented change that just really sucks? Because it requires a pretty big change in my library, if that's the case.

FYI: Taglet overview docs

Solution

  • So am I missing something here?

    Well, the section of documentation you quoted says this:

    " ... then you can use a dot-separated naming convention similar to that used for packages: com.mycompany.todo"

    Note that it says "dot-separated" naming convention, not "names with dots in them".

    Note that it says "similar to that used for packages". If you tried to use ".mypackage" as a package name, the compiler would say "No way!".

    My reading is that your ".codelet" tag name does not meet the criteria set out in the documentation. So what has happened is that the Java 8 version of javadoc has been changed to strictly enforce the taglet naming rules. That's unfortunate from your perspective, but ultimately the problem is in your javadoc comments, not the tool.