Summary

Update SourceVersion.latestSupported to increase the minimum supported value and add an informative API note.

Problem

Spurred by an implementation refactoring of the method in question, the specification was recognized as benefiting from some updates. In particular, since the JSR 269 is modularized, the minimum level must now be 9. The distinction between the latest and latestSupported was previously not explicit in the text. An API note now explains the intention of the second method.

Solution

Raise the supported floor to 9 and add an explanatory note.

Specification

     /**
      * Returns the latest source version fully supported by the
-     * current execution environment.  {@code RELEASE_5} or later must
+     * current execution environment.  {@code RELEASE_9} or later must
      * be returned.
      *
+     * @apiNote This method is included alongside {@link latest} to
+     * allow identification of situations where the language model API
+     * is running on a platform version different than the latest
+     * version modeled by the API. One way that sort of situation can
+     * occur is if an IDE or similar tool is using the API to model
+     * source version <i>N</i> while running on platform version
+     * (<i>N</i>&nbsp;-&nbsp;1). Running in this configuration is
+     * supported by the API. Running an API on platform versions
+     * earlier than (<i>N</i>&nbsp;-&nbsp;1) or later than <i>N</i>
+     * may or may not work as an implementation detail. If an
+     * annotation processor was generating code to run under the
+     * current execution environment, the processor should only use
+     * platform features up to the {@code latestSupported} release,
+     * which may be earlier than the {@code latest} release.
+     *
      * @return the latest source version that is fully supported
      */
     public static SourceVersion latestSupported()