JDK-8167203 : javadoc issue with handling argument for -tag option
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 9
  • Priority: P2
  • Status: Resolved
  • Resolution: Won't Fix
  • OS: generic
  • CPU: generic
  • Submitted: 2016-10-05
  • Updated: 2016-10-06
  • Resolved: 2016-10-06
Related Reports
Relates :  
JDK-8166472 - javac/javadoc expands @files incorrectly
Relates :  
JDK-8167157 - ant build fails with [javadoc] javadoc: error - Illegal package name: "implNote:a:Implementation Note:"
Description
Nashorn ant makefile properties file defines "-tag" options for javadoc. It used to work fine till recently. We got error with recent jdk9-dev builds.

See also: JDK-8167157

Error message goes like:

javadoc: error - Illegal package name: "implNote:a:Implementation Note:"
Comments
This is marked as "Will Not Fix" because the old behavior was neither documented nor common practice. The correct fix is to update the project.properties file, to add the extra whitespace character after the first -tag option, as done in the fix for JDK-8167157 http://hg.openjdk.java.net/jdk9/dev/nashorn/rev/7f5887b2f7a8
06-10-2016
This is the result of a number of factors: 1. A questionable/confusing setting in nashorn/make/project.properties javadoc.option=\ -tag "implSpec:a:Implementation Requirements:"\ -tag "implNote:a:Implementation Note:" Despite the apparent white-space, this is interpreted as javadoc.option=-tag "implSpec:a:Implementation Requirements:"-tag "implNote:a:Implementation Note:" Note the lack of white-space before the second -tag. 2. javadoc is being invoked by Ant, and under the covers, the Ant javadoc task is using an @-file to pass all the options and files to javadoc. 3. A slight change in behavior for @-files, introduced by JDK-8166472 It is #3, the slight change in behavior for @-files that is the most immediate cause for this issue arising in javadoc. Previously, the old support for @-files did not support embedded quotes, with the result that the character sequence "abc def"ghi was interpreted as two tokens 1. "abc def" (without the quotes) 2. ghi Now, embedded quotes are supported, and that same character sequence expands to a single token 1. "abc defghi" (without the quotes) As applied to the options read by javadoc in the @-file, the tokens from javadoc.options were -tag "implSpec:a:Implementation Requirements:"-tag "implNote:a:Implementation Note:" Under the old scheme, this was interpreteted as: 1. -tag 2. "implSpec:a:Implementation Requirements:" (without the quotes) 3. -tag 4. "implNote:a:Implementation Note:" Under the new scheme, this is interpreted as: 1. -tag 2. "implSpec:a:Implementation Requirements:-tag" (without the quotes) 3. "implNote:a:Implementation Note:" This is interpreted by javadoc as a weird but valid value for the -tag option in positions 1, 2, and an "orphaned" value in position 3, which is interpreted as a package name, because it neither begins with "-" (which would make it an option) or ends with .java (which would make it a source file). And then javadoc reports it (correctly) as an invalid package name.
06-10-2016