[Cronet] Better document Experimental Cronet classes

components/cronet/android/api/src/org/chromium/net/ExperimentalBidirectionalStream.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;
 
 /**
- * {@link BidirectionalStream} that exposes experimental features.
- * Created using {@link Builder}. Every instance of {@link BidirectionalStream} can be casted
- * to an instance of this class.
+ * {@link BidirectionalStream} that exposes experimental features. To obtain an
+ * instance of this class, cast a {@code BidirectionalStream} to this type. Every
+ * instance of {@code BidirectionalStream} 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

[kapishnikov, 2017/04/04 19:57:40]

If an experimental feature is moved to BidirectionalStream, the client is not
going to be impacted in any way since BidirectionalStream is a super interface
of ExperimentalBidirectionalStream; therefore, I am not sure it is worth to
mention that a feature can be promoted to BidirectionalStream in the future.
Maybe to discourage people from using experimental features, we should say that
"an experimental feature can be deprecated in the future. Use it on your own
risk."

This comments applies to similar javadoc comments.

+ * transitioned to supported features (and moved from
+ * {@link ExperimentalBidirectionalStream} to {@code BidirectionalStream}) or may be
+ * unsupported, in which case calling them may have no effect.
  *
  * {@hide prototype}
  */
 public abstract class ExperimentalBidirectionalStream extends BidirectionalStream {
     /**
-     * Builder for {@link ExperimentalBidirectionalStream}s. Allows configuring stream before
-     * constructing it via {@link Builder#build}. Created by
-     * {@link ExperimentalCronetEngine#newBidirectionalStreamBuilder}. A reference to this class
-     * can also be obtained through downcasting of {@link BidirectionalStream.Builder}.
+     * {@link BidirectionalStream#Builder} that exposes experimental features. To obtain an
+     * instance of this class, cast a {@code BidirectionalStream.Builder} to this type. Every
+     * instance of {@code BidirectionalStream.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 ExperimentalBidirectionalStream#Builder} to {@code BidirectionalStream.Builder}) or
+     * may be unsupported, in which case calling them may have no effect.
      */
     public abstract static class Builder extends BidirectionalStream.Builder {
         /**
          * Associates the annotation object with this request. May add more than one.
          * Passed through to a {@link RequestFinishedInfo.Listener},
          * see {@link RequestFinishedInfo#getAnnotations}.
          *
          * @param annotation an object to pass on to the {@link RequestFinishedInfo.Listener} with a
          * {@link RequestFinishedInfo}.
          * @return the builder to facilitate chaining.
@@ skipping 15 matching lines @@
         public abstract Builder setPriority(int priority);
 
         @Override
         public abstract Builder delayRequestHeadersUntilFirstFlush(
                 boolean delayRequestHeadersUntilFirstFlush);
 
         @Override
         public abstract ExperimentalBidirectionalStream build();
     }
 }