[Cronet] Better document Experimental Cronet classes

[Cronet] Better document Experimental Cronet classes

Major gists of documentation chagnes:
1. Most Experimental instances should only be accesssed via casts to drive home
   the fact that they aren't meant for general use, only experiemtation.
2. Explain that experimental features may become supported or unsupported.

BUG=671623
R=xunjieli,kapishnikov
CQ_INCLUDE_TRYBOTS=master.tryserver.chromium.android:android_cronet_tester

Review-Url: https://codereview.chromium.org/2794823003
Cr-Commit-Position: refs/heads/master@{#462295}
Committed: https://chromium.googlesource.com/chromium/src/+/201919d8a8f8351eb79f914d6b88dd0be7cc8821

[pauljensen, 2017-04-03 15:22:25]

Description was changed from

==========
[Cronet] Better document Experimental Cronet classes

Major gists of documentation chagnes:
1. Most Experimental instances should only be accesssed via casts to drive home
   the fact that they aren't meant for general use, only experiemtation.
2. Explain that experimental features may become supported or unsupported.

BUG=671623
R=xunjieli,kapishnikov
==========

to

==========
[Cronet] Better document Experimental Cronet classes

Major gists of documentation chagnes:
1. Most Experimental instances should only be accesssed via casts to drive home
   the fact that they aren't meant for general use, only experiemtation.
2. Explain that experimental features may become supported or unsupported.

BUG=671623
R=xunjieli,kapishnikov
CQ_INCLUDE_TRYBOTS=master.tryserver.chromium.android:android_cronet_tester
==========

[pauljensen, 2017-04-03 15:23:59]

Helen (who filed the bug) and Andrei (who authored the Experimental classes),
PTAL, thank you!

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

lgtm with one nit below. Thanks for adding the doc!

https://codereview.chromium.org/2794823003/diff/1/components/cronet/android/a...
File
components/cronet/android/api/src/org/chromium/net/ExperimentalBidirectionalStream.java
(right):

https://codereview.chromium.org/2794823003/diff/1/components/cronet/android/a...
components/cronet/android/api/src/org/chromium/net/ExperimentalBidirectionalStream.java:14:
* {@link ExperimentalBidirectionalStream} to {@code BidirectionalStream}) or may
be
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]

Andrei, care to take a look?

https://codereview.chromium.org/2794823003/diff/1/components/cronet/android/a...
File
components/cronet/android/api/src/org/chromium/net/ExperimentalBidirectionalStream.java
(right):

https://codereview.chromium.org/2794823003/diff/1/components/cronet/android/a...
components/cronet/android/api/src/org/chromium/net/ExperimentalBidirectionalStream.java:14:
* {@link ExperimentalBidirectionalStream} to {@code BidirectionalStream}) or may
be
On 2017/04/04 15:13:10, xunjieli wrote:
> 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.

Done.

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

Paul, the documentation look good. Two points:

1. I think it is important to emphasise somewhere that the regular CronetEngine
and the experimental one are backed by exactly the same implementation. The only
difference is in the set of interface methods that are exposed to the client.
There is no performance or memory penalty when the experimental Cronet engine is
created or used.

2. I think the usage of the experimental features should be discouraged in
general.

https://codereview.chromium.org/2794823003/diff/20001/components/cronet/andro...
File
components/cronet/android/api/src/org/chromium/net/ExperimentalBidirectionalStream.java
(right):

https://codereview.chromium.org/2794823003/diff/20001/components/cronet/andro...
components/cronet/android/api/src/org/chromium/net/ExperimentalBidirectionalStream.java:12:
* to access experimental features. Note that experimental features may be
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.

[pauljensen, 2017-04-05 18:30:03]

I think I addressed your comments Andrei, PTAL.

[kapishnikov, 2017-04-05 20:01:44]

lgtm

[pauljensen, 2017-04-06 00:03:08]

The CQ bit was checked by pauljensen@chromium.org

[pauljensen, 2017-04-06 00:03:09]

The patchset sent to the CQ was uploaded after l-g-t-m from
xunjieli@chromium.org
Link to the patchset: https://codereview.chromium.org/2794823003/#ps40001
(title: "address Andrei's comments")

[commit-bot: I haz the power, 2017-04-06 00:03:41]

CQ is trying da patch. Follow status at
 
https://chromium-cq-status.appspot.com/v2/patch-status/codereview.chromium.or...

[commit-bot: I haz the power, 2017-04-06 00:37:29]

CQ is committing da patch.

Bot data: {"patchset_id": 40001, "attempt_start_ts": 1491436988875690,
"parent_rev": "4dae691b744caea02124a6d3f295c70f5cea9910", "commit_rev":
"201919d8a8f8351eb79f914d6b88dd0be7cc8821"}

[commit-bot: I haz the power, 2017-04-06 00:38:52]

Description was changed from

==========
[Cronet] Better document Experimental Cronet classes

Major gists of documentation chagnes:
1. Most Experimental instances should only be accesssed via casts to drive home
   the fact that they aren't meant for general use, only experiemtation.
2. Explain that experimental features may become supported or unsupported.

BUG=671623
R=xunjieli,kapishnikov
CQ_INCLUDE_TRYBOTS=master.tryserver.chromium.android:android_cronet_tester
==========

to

==========
[Cronet] Better document Experimental Cronet classes

Major gists of documentation chagnes:
1. Most Experimental instances should only be accesssed via casts to drive home
   the fact that they aren't meant for general use, only experiemtation.
2. Explain that experimental features may become supported or unsupported.

BUG=671623
R=xunjieli,kapishnikov
CQ_INCLUDE_TRYBOTS=master.tryserver.chromium.android:android_cronet_tester

Review-Url: https://codereview.chromium.org/2794823003
Cr-Commit-Position: refs/heads/master@{#462295}
Committed:
https://chromium.googlesource.com/chromium/src/+/201919d8a8f8351eb79f914d6b88...
==========

[commit-bot: I haz the power, 2017-04-06 00:38:53]

Committed patchset #3 (id:40001) as
https://chromium.googlesource.com/chromium/src/+/201919d8a8f8351eb79f914d6b88...