Summary

Recursively copy subdirectories of doc-files by default in JavaDoc, making the -docfilessubdirs option a no-op.

Problem

JavaDoc does not recursively copy subdirectories of doc-files directories to the output unless the -docfilessubdirs option is specified. This behaviour was introduced 24 years ago to avoid copying directories allocated by version control systems such as SCCS. Since modern version control systems usually do not allocate directories in the source tree, this behaviour seems like an anachronism. On the other hand, HTML documents and assets such as images, scripts and stylesheets are often organized in directories. Apart from outdated version control systems, it is hard to think of a use case where subdirectories in doc-files should not be copied. There also exists a -excludedocfilessubdir option that allows to specify subdirectories that should be excluded from copying.

Solution

Change the behaviour of javadoc to copy nested directories of doc-files directories by default. The -docfilessubdirs option becomes a no-op. Update the javadoc man page to say that the -docfilessubdirs option is no longer required and that recursive copying is now the default behaviour.

JavaDoc already prints a message including the file name and path to stderr for each copied doc file. This should help to make users aware of any unintentional copying:

Copying file ./pkg/doc-files/dir/file.txt to directory out/pkg/doc-files/dir...

The existing -excludedocfilessubdir option to exclude subdirectories from being copied is enhanced to accept * as an argument. This excludes all subdirectories from being copied, allowing users to revert back to the old behaviour.

The change is announced in a JDK release note.

Specification

The javadoc man page is updated as follows:

diff --git a/src/jdk.javadoc/share/man/javadoc.md b/src/jdk.javadoc/share/man/javadoc.md
index 920b16f55b4..648cb6dd8ec 100644
--- a/src/jdk.javadoc/share/man/javadoc.md
+++ b/src/jdk.javadoc/share/man/javadoc.md
@@ -485,10 +485,9 @@ ### Standard Options for the Standard Doclet
     ```
 
 <span id="option-docfilessubdirs">`-docfilessubdirs`</span>
-:   Enables deep copying of `doc-files` directories. Subdirectories and all
-    contents are recursively copied to the destination. For example, the
-    directory `doc-files/example/images` and all of its contents are copied.
-    Use the [`-excludedocfilessubdir`](#option-excludedocfilessubdir) option to
+:   This option is no longer required as `javadoc` now recursively copies
+    subdirectories of `doc-files` directories by default. Use the
+    [`-excludedocfilessubdir`](#option-excludedocfilessubdir) option to
     restrict the subdirectories to be copied.
 
 <span id="option-doctitle">`-doctitle` *html-code*</span>
@@ -501,9 +500,9 @@ ### Standard Options for the Standard Doclet
     `javadoc -doctitle "<b>My Library</b><br>v1.0" com.mypackage`.
 
 <span id="option-excludedocfilessubdir">`-excludedocfilessubdir` *name1*`,`*name2...*</span>
-:   Excludes any subdirectories with the given names
-    when recursively copying `doc-files` subdirectories.
-    See [`-docfilessubdirs`](#option-docfilessubdirs).
+:   Excludes any subdirectories with the given names when recursively copying
+    `doc-files` subdirectories. You can use `*` to exclude all subdirectories
+    from being copied, but note that `*` must be quoted or escaped in the shell.
     For historical reasons, `:` can be used anywhere in the argument as a
     separator instead of `,`.
 

The changes can also be viewed here in specdiff format.

Additionally, javadoc issues the following warning when the -docfilessubdirs option is used:

warning: The -docfilessubdirs option is no longer required and may be
  removed in a future release.