RFR: JDK-8284037: Snippet-files subdirectory not automatically detected when in unnamed package

[Jonathan Gibbons]

On Mon, 16 May 2022 09:29:19 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> Please review a small fix to address use of snippets in source code in the unnamed package.
>> 
>> The core of the fix is to replace `packageName(pkg, utils)` (which returns `"<Unnamed>"` for the unnamed package) with plain old `pkg.getQualifiedName().toString()` (which returns an empty string for the unnamed package.)
>> 
>> There's some minor localized cleanup and rearrangement as well.
>> 
>> The test verifies behavior without and then with a source path, since that is the likely path of discovery by a user playing with the unnamed package.
>
> test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetUnnamedPackage.java line 84:
> 
>> 82:         checkExit(useSourcePath ? Exit.OK : Exit.ERROR);
>> 83:         checkOutput(Output.OUT, !useSourcePath,
>> 84:                 "C.java:4: error: file not found on source path or snippet path: S.java");
> 
> I must admit I don't understand the rules for snippet discovery with or without --source-path argument. Would the same behavior be expcected for code in a named package?

Well, the correct behavior is the same for both named and unnamed packages, but the bug was specifically about the use of the unnamed package.  

The correct behavior is that snippet files are first looked up on the source path (`--source-path` and friends), in the appropriate `snippet-files` subdirectory relative to the enclosing package, and if not found there, the snippet files are looked for on the snippet path (`--snippet-path`).  (( _An interesting corollary is that the `snippet-files` subdirectory does not need to be a direct subdirectory of the directory containing the snippet tag: it just has to exist with that name somewhere on the path. This could maybe be used by users and IDEs to their advantage._ ))

The underlying javac "rule" is that files are either given on the command-line or looked up on some search path. Snippet files can't be specified on the command-line; therefore, they must be found on a search path: in this case, either the source path or the snippet path.

The bug fixed in this issue was related to creating the name to give to the file manager. For the file manager, the unnamed package is represented by an empty string. We were (incorrectly) using the strings `<Unnamed>`. oops.

-------------

PR: https://git.openjdk.java.net/jdk/pull/8708