A couple of developers in the past have indicated they want to
store test files in the source tree near their corresponding source files.
That is, they would like to put them in the same directory, or
a subdirectory, of those source files.
I'd like to recommend that they put test files in a directory whose name
contains an illegal Java character, such as a hyphen in "test-files".
This works, but produces a warning, which seem unnecessary.
When using -subpackages, and when the source tree contains a directory
with an illegal subpackage name, such as "test-files" (contains a hyphen),
javadoc gives this warning:
javadoc: warning - No source files for package com.package1.test-files
Javadoc does not warn if a source file in a valid directory contains a hyphen,
so it seems it should not warn when a subdirectory name contains a hyphen.
It should simply skip over that subdirectory, which would allow us to
keep test files (of the unnamed package, for instance) in that directory
with no side effects.
Here's how the warning is produced. Given a package name com.package1
whose test directory is com/package1/test-files:
==> % ls -dF sample-src/com/package1/t*
sample-src/com/package1/test-files/
==> % more run-subpackages
/java/re/jdk/1.4.1/latest/binaries/solaris-sparc/bin/javadoc -d html-subpackages -sourcepath sample-src -subpackages com
==> % run-subpackages
Loading source files for package com.package1...
Loading source files for package com.package1.test-files...
Constructing Javadoc information...
javadoc: warning - No source files for package com.package1.test-files
Standard Doclet version 1.4.1
.
.
.