[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
+ * transitioned to supported features (and transition from
+ * {@link ExperimentalBidirectionalStream} to {@code BidirectionalStream}) or may be

[xunjieli, 2017/04/04 15:13:10]

nit: consider rephrasing the last sentence. It's a bit hard to follow with two
"transition" verbs used in both passive and active forms for the same subject.
Could consider changing the second "transition" to "moved."


Note that experimental features may be transitioned to supported features (and
moved from ... to ...) or may be unsupported...


Same below.

[pauljensen, 2017/04/04 19:27:25]

Done.

+ * 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 transition 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();
     }
 }