[Cronet] Better document Experimental Cronet classes

components/cronet/android/api/src/org/chromium/net/ExperimentalUrlRequest.java

 // Copyright 2016 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 package org.chromium.net;
 
 import java.util.concurrent.Executor;
 
 /**
- * {@link UrlRequest} that exposes experimental features. Created using
- * {@link ExperimentalUrlRequest.Builder}. Every instance of {@link UrlRequest} can
- * be casted to an instance of this class.
+ * {@link UrlRequest} that exposes experimental features. To obtain an
+ * instance of this class, cast a {@code UrlRequest} to this type. Every
+ * instance of {@code UrlRequest} can be cast to an instance of this class.
+ * Instances of this class are not meant for general use, but instead only
+ * to access experimental features. Note that experimental features may be
+ * transitioned to supported features (and moved from
+ * {@link ExperimentalUrlRequest} to {@code UrlRequest}) or may be
+ * unsupported, in which case calling them may have no effect.
  *
  * {@hide since this class exposes experimental features that should be hidden}.
  */
 public abstract class ExperimentalUrlRequest extends UrlRequest {
     /**
-     * Builder for building {@link UrlRequest}. Created by
-     * {@link ExperimentalCronetEngine#newUrlRequestBuilder}. A reference to this class
-     * can also be obtained through downcasting of {@link UrlRequest.Builder}.
+     * {@link UrlRequest#Builder} that exposes experimental features. To obtain an
+     * instance of this class, cast a {@code UrlRequest.Builder} to this type. Every
+     * instance of {@code UrlRequest.Builder} can be cast to an instance of this class.
+     * Instances of this class are not meant for general use, but instead only
+     * to access experimental features. Note that experimental features may be
+     * transitioned to supported features (and moved from
+     * {@link ExperimentalUrlRequest#Builder} to {@code UrlRequest.Builder}) or may be
+     * unsupported, in which case calling them may have no effect.
      */
     public abstract static class Builder extends UrlRequest.Builder {
         /**
          * Disables connection migration for the request if enabled for
          * the session.
          * @return the builder to facilitate chaining.
          */
         public Builder disableConnectionMigration() {
             return this;
         }
@@ skipping 30 matching lines @@
         public abstract Builder setUploadDataProvider(
                 UploadDataProvider uploadDataProvider, Executor executor);
 
         @Override
         public abstract Builder allowDirectExecutor();
 
         @Override
         public abstract ExperimentalUrlRequest build();
     }
 }