Explain when StandardSystemProperty.value() can return a null value, and deprecate JAVA_EXT_DIRS.

value()'s return type has been @nullable since 4232450, but I had forgotten the details about why, despite past CLs to update the test for specific missing keys.

I assume that we'll never actually *remove* JAVA_EXT_DIRS.

(Just slightly relevant to #2571)

RELNOTES=`base`: Deprecated `StandardSystemProperty.JAVA_EXT_DIRS`. We do not plan to remove the API, but in recent versions of Java, that property always has a value of `null`.

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=345251412

Author: cpovirk

android/guava/src/com/google/common/base/StandardSystemProperty.java

@@ -80,7 +80,15 @@ public enum StandardSystemProperty {
   /** Name of JIT compiler to use. */
   JAVA_COMPILER("java.compiler"),
 
-  /** Path of extension directory or directories. */
+  /**
+   * Path of extension directory or directories.
+   *
+   * @deprecated This property was <a
+   *     href="https://openjdk.java.net/jeps/220#Removed:-The-extension-mechanism">deprecated</a> in
+   *     Java 8 and removed in Java 9. We do not plan to remove this API from Guava, but if you are
+   *     using it, it is probably not doing what you want.
+   */
+  @Deprecated
   JAVA_EXT_DIRS("java.ext.dirs"),
 
   /** Operating system name. */
@@ -124,6 +132,25 @@ public String key() {
   /**
    * Returns the current value for this system property by delegating to {@link
    * System#getProperty(String)}.
+   *
+   * <p>The value returned by this method is non-null except in rare circumstances:
+   *
+   * <ul>
+   *   <li>{@link #JAVA_EXT_DIRS} was deprecated in Java 8 and removed in Java 9. We have not
+   *       confirmed whether it is available under older versions.
+   *   <li>{@link #JAVA_COMPILER}, while still listed as required as of Java 15, is typically not
+   *       available even under older version.
+   *   <li>Any property may be cleared through APIs like {@link System#clearProperty}.
+   *   <li>Unusual environments like GWT may have their own special handling of system properties.
+   * </ul>
+   *
+   * <p>Note that {@code StandardSystemProperty} does not provide constants for more recently added
+   * properties, including:
+   *
+   * <ul>
+   *   <li>{@code java.vendor.version} (added in Java 11, listed as optional as of Java 13)
+   *   <li>{@code jdk.module.*} (added in Java 9, optional)
+   * </ul>
    */
   @NullableDecl
   public String value() {

guava/src/com/google/common/base/StandardSystemProperty.java

@@ -80,7 +80,15 @@ public enum StandardSystemProperty {
   /** Name of JIT compiler to use. */
   JAVA_COMPILER("java.compiler"),
 
-  /** Path of extension directory or directories. */
+  /**
+   * Path of extension directory or directories.
+   *
+   * @deprecated This property was <a
+   *     href="https://openjdk.java.net/jeps/220#Removed:-The-extension-mechanism">deprecated</a> in
+   *     Java 8 and removed in Java 9. We do not plan to remove this API from Guava, but if you are
+   *     using it, it is probably not doing what you want.
+   */
+  @Deprecated
   JAVA_EXT_DIRS("java.ext.dirs"),
 
   /** Operating system name. */
@@ -124,6 +132,25 @@ public String key() {
   /**
    * Returns the current value for this system property by delegating to {@link
    * System#getProperty(String)}.
+   *
+   * <p>The value returned by this method is non-null except in rare circumstances:
+   *
+   * <ul>
+   *   <li>{@link #JAVA_EXT_DIRS} was deprecated in Java 8 and removed in Java 9. We have not
+   *       confirmed whether it is available under older versions.
+   *   <li>{@link #JAVA_COMPILER}, while still listed as required as of Java 15, is typically not
+   *       available even under older version.
+   *   <li>Any property may be cleared through APIs like {@link System#clearProperty}.
+   *   <li>Unusual environments like GWT may have their own special handling of system properties.
+   * </ul>
+   *
+   * <p>Note that {@code StandardSystemProperty} does not provide constants for more recently added
+   * properties, including:
+   *
+   * <ul>
+   *   <li>{@code java.vendor.version} (added in Java 11, listed as optional as of Java 13)
+   *   <li>{@code jdk.module.*} (added in Java 9, optional)
+   * </ul>
    */
   public @Nullable String value() {
     return System.getProperty(key);