Mark resource as experimental

Mark resource as experimental

Fixes issue 24150
BUG= http://dartbug.com/24150
R=sandholm@google.com

Committed: https://github.com/dart-lang/sdk/commit/1d537028f7cbe026fb682804fb13c72aa3261ae5

[Lasse Reichstein Nielsen, 2015-08-20 09:15:56]

lrn@google.com changed reviewers:
+ mit@google.com

[mit, 2015-08-20 09:31:42]

mit@google.com changed reviewers:
+ sandholm@google.com

[mit, 2015-08-20 09:31:42]

Anders, can you take a look at this also?

https://codereview.chromium.org/1284393004/diff/1/sdk/lib/core/resource.dart
File sdk/lib/core/resource.dart (right):

https://codereview.chromium.org/1284393004/diff/1/sdk/lib/core/resource.dart#...
sdk/lib/core/resource.dart:10: * WARNING: This API is under development,
I am not sure 'WARNING' is the best way of communicating this. I think we should
be more explicit, ala:

* ## Status: Experimental
* WARNING: This API is _experimental_, and it may...

This is similar to this, only slightly stricter:

sdk/lib/mirrors/mirrors.dart uses this:
* ## Status: Unstable
 *
 * The dart:mirrors library is unstable and its API might change slightly as a
 * result of user feedback.

[asandholm, 2015-08-20 09:38:50]

LGTM - with Michael's comment incorporated.

[Lasse Reichstein Nielsen, 2015-08-20 09:40:15]

https://codereview.chromium.org/1284393004/diff/1/sdk/lib/core/resource.dart
File sdk/lib/core/resource.dart (right):

https://codereview.chromium.org/1284393004/diff/1/sdk/lib/core/resource.dart#...
sdk/lib/core/resource.dart:10: * WARNING: This API is under development,
Interesting. I try to not use any fancy markdown in DartDoc since we haven't
defined what works and what doesn't. I have never used a header in DartDoc so
far, and I have no idea what it will look like. At least I would be very wary of
using it in member documentation - I can see it kind-of makes sense for library
documentation which is often less structured and more "texty".

We have previously used either WARNING: or NOTICE: for that kind of comments
(see Isolate.spawnUri).

[mit, 2015-08-20 09:42:53]

https://codereview.chromium.org/1284393004/diff/1/sdk/lib/core/resource.dart
File sdk/lib/core/resource.dart (right):

https://codereview.chromium.org/1284393004/diff/1/sdk/lib/core/resource.dart#...
sdk/lib/core/resource.dart:10: * WARNING: This API is under development,
On 2015/08/20 09:40:15, Lasse Reichstein Nielsen wrote:
> Interesting. I try to not use any fancy markdown in DartDoc since we haven't
> defined what works and what doesn't. I have never used a header in DartDoc so
> far, and I have no idea what it will look like. At least I would be very wary
of
> using it in member documentation - I can see it kind-of makes sense for
library
> documentation which is often less structured and more "texty".
> 
> We have previously used either WARNING: or NOTICE: for that kind of comments
> (see Isolate.spawnUri).

OK leaving out markdown. But still think we should use the word Experimental
which IMHO opinion is stronger than warning.

[Lasse Reichstein Nielsen, 2015-08-20 11:59:05]

Committed patchset #2 (id:20001) manually as
1d537028f7cbe026fb682804fb13c72aa3261ae5 (presubmit successful).