We started getting this error on our tests about a week ago. It has been on and off - sometimes people will get it and other times they won't.

```
/.../product/integration/src/test/java/com/acme/integration/code/CodeTestUtils.java:74: error: invalid use of @throws
         * @throws Exception if an error occurs.

```

I guess the error message is just a bit vague. Invalid how? The code looks OK to me:

```
    /**
     * Iterates to find modules and then calls
     * {@link #checkModule(Path, String, DirectoryStream.Filter, CheckFile)} for each.
     *
     * @param subPath the path within each module to start checks from.
     * @param filter the filter to apply to choose which files to check.
     * @param checkFile the checks to perform on each file.
     * @throws Exception if an error occurs.
     */
    public static void checkProject(String subPath, DirectoryStream.Filter<Path> filter, CheckFile checkFile) throws Exception
    {
        for (Path file : listFiles(EnvironmentUtils.getDevelopmentRoot().toPath()))
        {
            if (FileUtils.isDirectory(file) && FileUtils.exists(file.resolve("src/java")))
            {
                checkModule(file, subPath, filter, checkFile);
            }
        }
    }

```

We do turn on doclint during the compile because we want to find about about Javadoc errors without having to separately run Javadoc.

What exactly is this error supposed to mean? Is there anything invalid about what we're doing here? Are we looking at a compiler bug? Surely a bug like this would hit the first person who tried to declare that a method throws an exception... :(

**The investigation so far...**

* I managed to cut the example down to a [simple project](https://github.com/trejkaz/gradle_wtf_compile) which [gives the same error](https://travis-ci.org/trejkaz/gradle_wtf_compile/builds/237803749). Aside from Travis CI being able to reproduce it on Linux, I can reproduce it here on macOS, starting today (no idea why this is time-dependent!) and other users on Windows have been talking about it for a couple days now.
* From this project I looked at the command-line Gradle was using for javac and managed to get the same error to appear calling javac directly.
* Cutting down the javac command-line further:

```
javac -source 1.8 -target 1.8 -d build/classes/test \
  -classpath build/classes/main:build/resources/main:$HOME/.gradle/caches/modules-2/files-2.1/org.apache.logging.log4j/log4j-core/2.8.2/979fc0cf8460302e4ffbfe38c1b66a99450b0bb7/log4j-core-2.8.2.jar:$HOME/.gradle/caches/modules-2/files-2.1/org.apache.logging.log4j/log4j-api/2.8.2/e590eeb783348ce8ddef205b82127f9084d82bf3/log4j-api-2.8.2.jar \
  -Xdoclint:all,-missing \
  src/test/java/com/acme/CodeTestUtils.java

```

This shows that the problem still occurs without Gradle in the picture. (Gradle had added `-processorpath` and `-g` too.)