add a better warning javadoc

Author: arturobernalg

httpclient5/src/main/java/org/apache/hc/client5/http/config/EnvironmentProxyConfigurer.java

@@ -39,72 +39,70 @@
  * <h2>EnvironmentProxyConfigurer</h2>
  *
  * <p>
- * Many *nix shells, container runtimes, and CI systems advertise an
- * outbound HTTP proxy exclusively via the environment variables
- * {@code HTTP_PROXY}, {@code HTTPS_PROXY}, and {@code NO_PROXY}.
- * The JDK, however, expects the corresponding <em>system-properties</em>
- * &nbsp;({@code http.proxyHost}, {@code http.proxyPort}, &hellip;) when it
- * resolves a proxy through {@link java.net.ProxySelector} or performs
- * authentication through {@link java.net.Authenticator}.
+ * Many *nix shells, container runtimes, and CI systems expose an outbound
+ * proxy exclusively via the environment variables {@code HTTP_PROXY},
+ * {@code HTTPS_PROXY}, and {@code NO_PROXY}.  The JDK, however, expects the
+ * equivalent <em>system&nbsp;properties</em>
+ * ({@code http.proxyHost}, {@code http.proxyPort}, &amp;c.) when it resolves a
+ * proxy through {@link java.net.ProxySelector} or performs authentication via
+ * {@link java.net.Authenticator}.
  * </p>
  *
  * <p>
  * <strong>EnvironmentProxyConfigurer</strong> is a small, <em>opt-in</em>
- * utility that copies the commonly-used variables to the standard
- * properties once, at application start-up.  It is <em>not</em> invoked
- * automatically by HttpClient – call it explicitly if you want this
- * behaviour:
+ * helper that copies those variables to the standard properties once, at
+ * application start-up.  <strong>It is <em>not</em> invoked automatically by
+ * HttpClient.</strong>  Call it explicitly if you want the mapping:
  * </p>
  *
  * <pre>{@code
- * public static void main(String[] args) {
- *     EnvironmentProxyConfigurer.apply();   // one-liner
- *     CloseableHttpClient client = HttpClientBuilder.create()
- *             .useSystemProperties()        // default behaviour
- *             .build();
- *     …
- * }
+ * EnvironmentProxyConfigurer.apply();   // one-liner
+ * CloseableHttpClient client = HttpClientBuilder.create()
+ *         .useSystemProperties()        // default behaviour
+ *         .build();
  * }</pre>
  *
  * <h3>Mapping rules</h3>
  * <ul>
- *   <li>{@code HTTP_PROXY}  &rarr; {@code http.proxyHost},
+ *   <li>{@code HTTP_PROXY}  → {@code http.proxyHost},
  *       {@code http.proxyPort}, {@code http.proxyUser},
  *       {@code http.proxyPassword}</li>
- *   <li>{@code HTTPS_PROXY} &rarr; {@code https.proxyHost},
+ *   <li>{@code HTTPS_PROXY} → {@code https.proxyHost},
  *       {@code https.proxyPort}, {@code https.proxyUser},
  *       {@code https.proxyPassword}</li>
- *   <li>{@code NO_PROXY}    &rarr; {@code http.nonProxyHosts},
- *       {@code https.nonProxyHosts} &nbsp;(commas are converted to the
- *       pipe&nbsp;‘|’ separator required by the JDK)</li>
+ *   <li>{@code NO_PROXY}    → {@code http.nonProxyHosts},
+ *       {@code https.nonProxyHosts}&nbsp; (commas are converted to the
+ *       ‘|’ separator required by the JDK)</li>
  *   <li>Lower-case aliases ({@code http_proxy}, {@code https_proxy},
  *       {@code no_proxy}) are recognised as well.</li>
  * </ul>
  *
  * <h3>Design notes</h3>
  * <ul>
  *   <li><strong>Idempotent:</strong> if a target property is already set
- *       (for example with {@code -Dhttp.proxyHost=…}) it is left
- *       untouched.</li>
+ *       (e.g.&nbsp;via {@code -Dhttp.proxyHost=…}) it is left untouched.</li>
  *   <li><strong>Thread-safe:</strong> all reads and writes are wrapped in
  *       {@code AccessController.doPrivileged} and synchronise only on the
  *       global {@link System} properties map.</li>
- *   <li><strong>No side-effects unless invoked:</strong> because the
- *       method is <em>not</em> called from within
- *       {@link org.apache.hc.client5.http.impl.classic.HttpClientBuilder},
- *       applications that do not need proxy support see no change in
- *       JVM-wide state.</li>
  * </ul>
  *
+ * <h3>Warning</h3>
  * <p>
- * The class is {@linkplain org.apache.hc.core5.annotation.Contract
- * stateless} and safe to call multiple times; subsequent invocations will
- * be no-ops after the first successful copy.
+ * Calling {@link #apply()} changes JVM-wide system properties.  The new proxy
+ * settings therefore apply to <em>all</em> libraries and threads in the same
+ * process.  Invoke this method only if your application really needs to
+ * inherit proxy configuration from the environment and you are aware that
+ * other components may be affected.
+ * </p>
+ *
+ * <p>
+ * The class is {@linkplain org.apache.hc.core5.annotation.Contract stateless}
+ * and safe to call multiple times; subsequent invocations are no-ops once the
+ * copy has succeeded.
  * </p>
  *
  * @since 5.6
  */
-
 @Contract(threading = ThreadingBehavior.STATELESS)
 public final class EnvironmentProxyConfigurer {