The JDK 11 javadoc for SourceVersion#latest and SourceVersion#latestSupported currently reads as:

> Returns the latest source version that can be modeled.

https://docs.oracle.com/en/java/javase/11/docs/api/java.compiler/javax/lang/model/SourceVersion.html#latest()

> Returns the latest source version fully supported by the current execution environment. RELEASE_5 or later must be returned.

https://docs.oracle.com/en/java/javase/11/docs/api/java.compiler/javax/lang/model/SourceVersion.html#latestSupported()

It would be helpful to provide some more information about when latestSupported should be used, and perhaps a usage example.

In particular it's not clear to me when latestSupported is the right choice.
* If the current runtime version is the same as the java.compiler version latestSupported and latest have the same behaviour.
* If the runtime version is newer than the version of java.compiler, the implementation will see an unrecognized value of `java.specification.version` and fall back to returning RELEASE_5, which is misleading: http://hg.openjdk.java.net/jdk/jdk/file/0288c6919a20/src/java.compiler/share/classes/javax/lang/model/SourceVersion.java#l235
* The runtime version shouldn't ever be older than the version of java.compiler, except for during the JDK's own build process when version N of java.compiler is run on the version N-1 bootstrap JDK. Is that situation the intended use-case for latestSupported?