[jakartaee-spec-project-leads] JDK 11 javadoc, doc-files, and the spec l

[Bill Shannon <bill.shannon@xxxxxxxxxx>]

I spent far too much time resolving a javadoc problem (with help from
Lukas Jungmann and Jonathan Gibbons) so I thought I would write down
the issue and the solution in case it helps the rest of you.

In our API projects we created a a doc-files directory to contain the
spec license file.  Often we put the directory in src/main/java/docfiles.
This worked fine when using JDK 1.8, but the behavior changed in JDK 11
(and it's not clear it was ever intended to work in JDK 1.8).

The javadoc tool expects the doc-files directory to be in a (any) package
directory that also contains source files.  So, for example, it could be
in src/main/java/javax/activation/doc-files, but not in src/main/java/doc-files
because there are no source files in the unnamed package.

Since the license file doesn't belong to a specific package, it doesn't
make sense to put it under a package directory.  Fortunately, the
maven-javadoc-plugin allows you to put it in src/main/javadoc/doc-files.
Ideally, that's all that would be necessary, but there's a bug or a
misunderstanding in the plugin and you also need to add the following
plugin configuration:

	<docfilessubdirs>true</docfilessubdirs>

With this additional configuration, and moving the doc-files directory
to src/main/javadoc/doc-files, the spec license file gets copied to the
javadoc output directory as expected.