[Cronet] Better document Experimental Cronet classes

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

Index: components/cronet/android/api/src/org/chromium/net/ExperimentalBidirectionalStream.java
diff --git a/components/cronet/android/api/src/org/chromium/net/ExperimentalBidirectionalStream.java b/components/cronet/android/api/src/org/chromium/net/ExperimentalBidirectionalStream.java
index 5be350c06bdf31772ead3b03d5c98fe647670f55..bd85820b58739e792618630444f0b41321d805e1 100644
--- a/components/cronet/android/api/src/org/chromium/net/ExperimentalBidirectionalStream.java
+++ b/components/cronet/android/api/src/org/chromium/net/ExperimentalBidirectionalStream.java
@@ -5,18 +5,27 @@
 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 {
         /**