9

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

aliteralmind
  • 19,847
  • 17
  • 77
  • 108
  • 1
    I'd say that it's probably the just an undocumented change. I think that the assumption is that Java identifiers, in general, do not start with a dot. For example, package names, AFAIK, cannot start with a dot. It's probably a bit of a mistake that this was allowed in previous versions. Can you not just change your taglet name to 'codelet', or worst case, 'aliteralmind.codelet' ? – GreyBeardedGeek Feb 25 '15 at 18:16
  • It's a publicly released library that is used by thousands upon thousands of java programmers worldwide (let me dream). The current-and-soon-to-be-old taglet names must be deprecated and newly-named taglets must be created to replace them. Not brain busting, but very time consuming. It's a big pain. It *is* recommended to used dots to avoid conflicts with future Sun taglets, so I'm going to go with `cod.elet` (shudder). – aliteralmind Feb 25 '15 at 18:26
  • 1
    A big pain that you could have avoided by adhering to what you have quoted: “use a dot-separated naming convention similar to that used for packages”. Nothing there backs the assumption that leading dots should work. In the end, I don’t understand why you prepended your names with a dot at all. The namespaces were meant to solve potential ambiguities, which only works if developers choose unique namespaces, but if you don’t choose a unique namespace you don’t need to use them… – Holger Feb 25 '15 at 18:31
  • I wish I understood that a year ago. – aliteralmind Feb 25 '15 at 18:39

1 Answers1

4

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.

Stephen C
  • 698,415
  • 94
  • 811
  • 1,216