[doclint] doclint will reject existing user-written doc comments using custom tags that follow the recommended rules

The syntax of javadoc tags is poorly specified, and based on precedent, doclint assumed that tags should be simple identifiers, and attempts to enforce that rule.

However, when using custom tags, javadoc also suggests strongly, via an error message, that custom tags should contain a period, to avoid the risk of clashing with any possible future tags.

doclint should be relaxed to allow dots in tags.


$ cat play/Test.java
/** @todo */
public class Test { }
$ javadoc -d play/api -Xdoclint:all -tag todo play/Test.java
Loading source file play/Test.java...
Constructing Javadoc information...
Standard Doclet version 1.8.0-internal
Building tree for all the packages and classes...
Generating play/api/Test.html...
Generating play/api/package-frame.html...
Generating play/api/package-summary.html...
Generating play/api/package-tree.html...
Generating play/api/constant-values.html...
Building index for all the packages and classes...
Generating play/api/overview-tree.html...
Generating play/api/index-all.html...
Generating play/api/deprecated-list.html...
Building index for all classes...
Generating play/api/allclasses-frame.html...
Generating play/api/allclasses-noframe.html...
Generating play/api/index.html...
Generating play/api/help-doc.html...
Note: Custom tags that could override future standard tags: @todo. To avoid potential overrides, use at least one period character (.) in custom tag names.


$ cat play/Test.java
/** @to.do */
public class Test { }
$ javadoc -d play/api -Xdoclint:all play/Test.java
Loading source file play/Test.java...
Constructing Javadoc information...
Standard Doclet version 1.8.0-internal
Building tree for all the packages and classes...
Generating play/api/Test.html...
play/Test.java:1: error: unknown tag: to
/** @to.do */
    ^
Generating play/api/package-frame.html...
Generating play/api/package-summary.html...
Generating play/api/package-tree.html...
Generating play/api/constant-values.html...
Building index for all the packages and classes...
Generating play/api/overview-tree.html...
Generating play/api/index-all.html...
Generating play/api/deprecated-list.html...
Building index for all classes...
Generating play/api/allclasses-frame.html...
Generating play/api/allclasses-noframe.html...
Generating play/api/index.html...
Generating play/api/help-doc.html...
1 error