Generating annotations from DOM triage list.

Generating support annotations from DOM triage list.

This is applying the results of the detailed API triage I did to the support annotations for DOM types.

BUG=
R=jacobr@google.com

Committed: https://code.google.com/p/dart/source/detail?r=23159

[blois, 2013-05-10 18:32:47]

This basically adds a ton of @Experimental annotations to various DOM APIs, and
a few @Unstable annotations.

It'd be great if folks could take a look through the generated APIs and do a
sanity check on how I classified them.

No tremendous rush here, I'd prefer that folks take their time reviewing.

There will still be later churn as APIs are still in progress, but all of those
should either be cookie-cutter changes or individual API support level changes.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dart2js/html_...
File sdk/lib/html/dart2js/html_dart2js.dart (right):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dart2js/html_...
sdk/lib/html/dart2js/html_dart2js.dart:144: //
http://www.whatwg.org/specs/web-apps/current-work/multipage/obsolete.html#HTM...
Expect these comments to be removed (or converted to an annotation?), but
hopefully they make it easier to understand the rationale for the particular
annotation.

[Emily Fortuna, 2013-05-10 19:59:02]

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/html_common/m...
File sdk/lib/html/html_common/metadata.dart (left):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/html_common/m...
sdk/lib/html/html_common/metadata.dart:57: /// Metadata that specifies that that
member is editable through generated
you just made Bob sad. ;-/

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/indexed_db/dart2js...
File sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart (right):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/indexed_db/dart2js...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:141: @Unstable
what does unstable mean exactly?

[blois, 2013-05-10 20:17:01]

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/html_common/m...
File sdk/lib/html/html_common/metadata.dart (left):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/html_common/m...
sdk/lib/html/html_common/metadata.dart:57: /// Metadata that specifies that that
member is editable through generated
On 2013/05/10 19:59:02, Emily Fortuna wrote:
> you just made Bob sad. ;-/

Consistency! All the other comments are /** style.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/indexed_db/dart2js...
File sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart (right):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/indexed_db/dart2js...
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:141: @Unstable
On 2013/05/10 19:59:02, Emily Fortuna wrote:
> what does unstable mean exactly?

Dan's explanation when explaining the need for the annotations across Dart-

"The API is in the process of settling, but has not yet had
sufficient real-world testing to be considered stable. Backwards-compatibility
will be maintained if reasonable."

[blois, 2013-05-21 22:11:10]

Ping!

Would like to get this in this week.

On 2013/05/10 20:17:01, blois wrote:
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/html_common/m...
> File sdk/lib/html/html_common/metadata.dart (left):
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/html_common/m...
> sdk/lib/html/html_common/metadata.dart:57: /// Metadata that specifies that
that
> member is editable through generated
> On 2013/05/10 19:59:02, Emily Fortuna wrote:
> > you just made Bob sad. ;-/
> 
> Consistency! All the other comments are /** style.
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/indexed_db/dart2js...
> File sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart (right):
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/indexed_db/dart2js...
> sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart:141: @Unstable
> On 2013/05/10 19:59:02, Emily Fortuna wrote:
> > what does unstable mean exactly?
> 
> Dan's explanation when explaining the need for the annotations across Dart-
> 
> "The API is in the process of settling, but has not yet had
> sufficient real-world testing to be considered stable. Backwards-compatibility
> will be maintained if reasonable."

[Emily Fortuna, 2013-05-22 01:09:08]

audio categorization looks good to me. 

the SVG I have some questions on.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/html_common/m...
File sdk/lib/html/html_common/metadata.dart (right):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/html_common/m...
sdk/lib/html/html_common/metadata.dart:68: class Unstable {}
clarification: is this "enough testing" on our end?

If so....
nit: why not call this "Untested" or "Untriaged" (indicating it hasn't gone
through the desired full battery of tests to work on all browsers) instead?

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/svg/dart2js/svg_da...
File sdk/lib/svg/dart2js/svg_dart2js.dart (right):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/svg/dart2js/svg_da...
sdk/lib/svg/dart2js/svg_dart2js.dart:1381: @Unstable
not sure what's unstable about these FE*Elements. I recall testing them...

[Jacob, 2013-05-22 01:34:07]

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
File sdk/lib/html/dartium/html_dartium.dart (left):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:2595: bool isPropertyImplicit(String
propertyName) native "CSSStyleDeclaration_isPropertyImplicit_Callback";
Make this deprecated not just implicit
Alexis Menard <alexis.menard@intel.com>
May 9 (12 days ago)

to blink-dev 
Hi all,

Primary eng (and PM) emails :
alexis.menard@intel.com


Summary

I would like to remove getPropertyShorthand and isPropertyImplicit from the
CSSStyleDeclaration.idl.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:6274: @DomName('HTMLDialogElement')
perhaps deprecated rather than just unstable?

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:6694: Touch $dom_createTouch(Window
window, EventTarget target, int identifier, int pageX, int pageY, int screenX,
int screenY, int webkitRadiusX, int webkitRadiusY, num webkitRotationAngle, num
webkitForce) native "Document_createTouch_Callback";
is 
new Touch(....) also intended to be experimental?

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:13454: @DomName('HTMLLinkElement.sizes')
html5 not experimental

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
File sdk/lib/html/dartium/html_dartium.dart (right):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:130: +  //
http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#attr-h...
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a
this is html5 so shouldn't be tagged as experimental

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:1572: +  @Experimental // non-standard
seems like this is in multiple browsers.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:2657: +  @Experimental // non-standard
deprecated not implicit

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:8738: +  @deprecated // nonstandard
is this deprecated?
I thought the intended dart:html way to remove an element was to call
element.remove()

rather than the annoying element.parent.removeChild(element)
dance required by raw DOM

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:11474: +  @Experimental // untriaged
not sure why these are experimental, seems like they are the core of what makes
an HTMLAllCollection useful. Granted it doesn't matter much as the class is
deprecated

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:13620: +  @Unstable
tag as not working in FF
https://bugzilla.mozilla.org/show_bug.cgi?id=556743

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:15805: +@Experimental // deprecated
shouldn't this be deprecated instead of experimental? mutationevents are
horrible for performance.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:16189: +  @Unstable
is this unstable or deprecated?

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:26072: +@Experimental // stable
should the worker stuff be deprecated due to the overlap with dart isolates? I
hate having two ways of doing the same thing

[Jacob, 2013-05-22 01:34:07]

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
File sdk/lib/html/dartium/html_dartium.dart (left):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:2595: bool isPropertyImplicit(String
propertyName) native "CSSStyleDeclaration_isPropertyImplicit_Callback";
Make this deprecated not just implicit
Alexis Menard <alexis.menard@intel.com>
May 9 (12 days ago)

to blink-dev 
Hi all,

Primary eng (and PM) emails :
alexis.menard@intel.com


Summary

I would like to remove getPropertyShorthand and isPropertyImplicit from the
CSSStyleDeclaration.idl.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:6274: @DomName('HTMLDialogElement')
perhaps deprecated rather than just unstable?

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:6694: Touch $dom_createTouch(Window
window, EventTarget target, int identifier, int pageX, int pageY, int screenX,
int screenY, int webkitRadiusX, int webkitRadiusY, num webkitRotationAngle, num
webkitForce) native "Document_createTouch_Callback";
is 
new Touch(....) also intended to be experimental?

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:13454: @DomName('HTMLLinkElement.sizes')
html5 not experimental

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
File sdk/lib/html/dartium/html_dartium.dart (right):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:130: +  //
http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#attr-h...
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a
this is html5 so shouldn't be tagged as experimental

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:1572: +  @Experimental // non-standard
seems like this is in multiple browsers.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:2657: +  @Experimental // non-standard
deprecated not implicit

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:8738: +  @deprecated // nonstandard
is this deprecated?
I thought the intended dart:html way to remove an element was to call
element.remove()

rather than the annoying element.parent.removeChild(element)
dance required by raw DOM

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:11474: +  @Experimental // untriaged
not sure why these are experimental, seems like they are the core of what makes
an HTMLAllCollection useful. Granted it doesn't matter much as the class is
deprecated

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:13620: +  @Unstable
tag as not working in FF
https://bugzilla.mozilla.org/show_bug.cgi?id=556743

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:15805: +@Experimental // deprecated
shouldn't this be deprecated instead of experimental? mutationevents are
horrible for performance.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:16189: +  @Unstable
is this unstable or deprecated?

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:26072: +@Experimental // stable
should the worker stuff be deprecated due to the overlap with dart isolates? I
hate having two ways of doing the same thing

[blois, 2013-05-22 02:14:09]

Comments & fixups inline. Thanks for taking a look!

On 2013/05/22 01:34:07, Jacob wrote:
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> File sdk/lib/html/dartium/html_dartium.dart (left):
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> sdk/lib/html/dartium/html_dartium.dart:2595: bool isPropertyImplicit(String
> propertyName) native "CSSStyleDeclaration_isPropertyImplicit_Callback";
> Make this deprecated not just implicit
> Alexis Menard <mailto:alexis.menard@intel.com>
> May 9 (12 days ago)
> 
> to blink-dev 
> Hi all,
> 
> Primary eng (and PM) emails :
> mailto:alexis.menard@intel.com
> 
> 
> Summary
> 
> I would like to remove getPropertyShorthand and isPropertyImplicit from the
> CSSStyleDeclaration.idl.
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> sdk/lib/html/dartium/html_dartium.dart:6274: @DomName('HTMLDialogElement')
> perhaps deprecated rather than just unstable?
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> sdk/lib/html/dartium/html_dartium.dart:6694: Touch $dom_createTouch(Window
> window, EventTarget target, int identifier, int pageX, int pageY, int screenX,
> int screenY, int webkitRadiusX, int webkitRadiusY, num webkitRotationAngle,
num
> webkitForce) native "Document_createTouch_Callback";
> is 
> new Touch(....) also intended to be experimental?
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> sdk/lib/html/dartium/html_dartium.dart:13454:
@DomName('HTMLLinkElement.sizes')
> html5 not experimental
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> File sdk/lib/html/dartium/html_dartium.dart (right):
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> sdk/lib/html/dartium/html_dartium.dart:130: +  //
>
http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#attr-h...
> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a
> this is html5 so shouldn't be tagged as experimental
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> sdk/lib/html/dartium/html_dartium.dart:1572: +  @Experimental // non-standard
> seems like this is in multiple browsers.
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> sdk/lib/html/dartium/html_dartium.dart:2657: +  @Experimental // non-standard
> deprecated not implicit
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> sdk/lib/html/dartium/html_dartium.dart:8738: +  @deprecated // nonstandard
> is this deprecated?
> I thought the intended dart:html way to remove an element was to call
> element.remove()
> 
> rather than the annoying element.parent.removeChild(element)
> dance required by raw DOM
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> sdk/lib/html/dartium/html_dartium.dart:11474: +  @Experimental // untriaged
> not sure why these are experimental, seems like they are the core of what
makes
> an HTMLAllCollection useful. Granted it doesn't matter much as the class is
> deprecated
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> sdk/lib/html/dartium/html_dartium.dart:13620: +  @Unstable
> tag as not working in FF
> https://bugzilla.mozilla.org/show_bug.cgi?id=556743
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> sdk/lib/html/dartium/html_dartium.dart:15805: +@Experimental // deprecated
> shouldn't this be deprecated instead of experimental? mutationevents are
> horrible for performance.
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> sdk/lib/html/dartium/html_dartium.dart:16189: +  @Unstable
> is this unstable or deprecated?
> 
>
https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
> sdk/lib/html/dartium/html_dartium.dart:26072: +@Experimental // stable
> should the worker stuff be deprecated due to the overlap with dart isolates? I
> hate having two ways of doing the same thing

[blois, 2013-05-22 02:14:16]

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
File sdk/lib/html/dartium/html_dartium.dart (left):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:2595: bool isPropertyImplicit(String
propertyName) native "CSSStyleDeclaration_isPropertyImplicit_Callback";
On 2013/05/22 01:34:08, Jacob wrote:
> Make this deprecated not just implicit
> Alexis Menard <mailto:alexis.menard@intel.com>
> May 9 (12 days ago)
> 
> to blink-dev 
> Hi all,
> 
> Primary eng (and PM) emails :
> mailto:alexis.menard@intel.com
> 
> 
> Summary
> 
> I would like to remove getPropertyShorthand and isPropertyImplicit from the
> CSSStyleDeclaration.idl.

Done.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:6274: @DomName('HTMLDialogElement')
On 2013/05/22 01:34:08, Jacob wrote:
> perhaps deprecated rather than just unstable?

Isn't this one of the new types? It's at:
http://www.whatwg.org/specs/web-apps/current-work/multipage/commands.html#the...

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:6694: Touch $dom_createTouch(Window
window, EventTarget target, int identifier, int pageX, int pageY, int screenX,
int screenY, int webkitRadiusX, int webkitRadiusY, num webkitRotationAngle, num
webkitForce) native "Document_createTouch_Callback";
On 2013/05/22 01:34:08, Jacob wrote:
> is 
> new Touch(....) also intended to be experimental?

Yes, the Touch class is marked as experimental.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:13454: @DomName('HTMLLinkElement.sizes')
On 2013/05/22 01:34:08, Jacob wrote:
> html5 not experimental

Done, but was going off of
'http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#rel-icon'
where all implementations are listed as partial.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
File sdk/lib/html/dartium/html_dartium.dart (right):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:130: +  //
http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#attr-h...
On 2013/05/22 01:34:08, Jacob wrote:
> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a
> this is html5 so shouldn't be tagged as experimental 

Done.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:1572: +  @Experimental // non-standard
On 2013/05/22 01:34:08, Jacob wrote:
> seems like this is in multiple browsers.  

Yep, not sure why I couldn't find it.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:2657: +  @Experimental // non-standard
On 2013/05/22 01:34:08, Jacob wrote:
> deprecated not implicit

Done.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:8738: +  @deprecated // nonstandard
On 2013/05/22 01:34:08, Jacob wrote:
> is this deprecated?
> I thought the intended dart:html way to remove an element was to call
> element.remove()
> 
> rather than the annoying element.parent.removeChild(element)
> dance required by raw DOM 

Updated to make it stable. That one is a bit tricky, because Blink's
Element.remove is actually non-standard, but in Dart we expose our own
Node.remove.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:11474: +  @Experimental // untriaged
On 2013/05/22 01:34:08, Jacob wrote:
> not sure why these are experimental, seems like they are the core of what
makes
> an HTMLAllCollection useful. Granted it doesn't matter much as the class is
> deprecated

These should be stable actually- they are on HTMLOptionsCollection, not
HTMLAllCollection.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:13620: +  @Unstable
On 2013/05/22 01:34:08, Jacob wrote:
> tag as not working in FF
> https://bugzilla.mozilla.org/show_bug.cgi?id=556743

And IE. So if it's only released on WebKit browsers, can it be non-experimental?

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:15805: +@Experimental // deprecated
On 2013/05/22 01:34:08, Jacob wrote:
> shouldn't this be deprecated instead of experimental? mutationevents are
> horrible for performance.

Done.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:16189: +  @Unstable
On 2013/05/22 01:34:08, Jacob wrote:
> is this unstable or deprecated?

Deprecated is probably better.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/dartium/html_...
sdk/lib/html/dartium/html_dartium.dart:26072: +@Experimental // stable
On 2013/05/22 01:34:08, Jacob wrote:
> should the worker stuff be deprecated due to the overlap with dart isolates? I
> hate having two ways of doing the same thing

This is a private API until we figure out isolates.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/html_common/m...
File sdk/lib/html/html_common/metadata.dart (right):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/html/html_common/m...
sdk/lib/html/html_common/metadata.dart:68: class Unstable {}
On 2013/05/22 01:09:08, Emily Fortuna wrote:
> clarification: is this "enough testing" on our end?
> 
> If so....
> nit: why not call this "Untested" or "Untriaged" (indicating it hasn't gone
> through the desired full battery of tests to work on all browsers) instead?

This was just what was proposed for the rest of Dart. This should move out of
dart:html once the rest of the libs start triaging their APIs.

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/svg/dart2js/svg_da...
File sdk/lib/svg/dart2js/svg_dart2js.dart (right):

https://codereview.chromium.org/15074006/diff/6018/sdk/lib/svg/dart2js/svg_da...
sdk/lib/svg/dart2js/svg_dart2js.dart:1381: @Unstable
On 2013/05/22 01:09:08, Emily Fortuna wrote:
> not sure what's unstable about these FE*Elements. I recall testing them...

It's more that right now all SVG APIs are 'unstable'.

[Andrei Mouravski, 2013-05-22 10:07:00]

Needs more documentation and there's too much code copying in the python.

https://codereview.chromium.org/15074006/diff/26001/sdk/lib/html/html_common/...
File sdk/lib/html/html_common/metadata.dart (right):

https://codereview.chromium.org/15074006/diff/26001/sdk/lib/html/html_common/...
sdk/lib/html/html_common/metadata.dart:58: * Metadata that specifies that that
member is editable through generated
"Annotation that specifies that a member is editable through generate files."

https://codereview.chromium.org/15074006/diff/26001/sdk/lib/html/html_common/...
sdk/lib/html/html_common/metadata.dart:65: * Annotation which indicates that an
API is not expected to change but has
We need style guide for metadata doc comments...

"Annotation that..."

https://codereview.chromium.org/15074006/diff/26001/sdk/lib/web_sql/dartium/w...
File sdk/lib/web_sql/dartium/web_sql_dartium.dart (right):

https://codereview.chromium.org/15074006/diff/26001/sdk/lib/web_sql/dartium/w...
sdk/lib/web_sql/dartium/web_sql_dartium.dart:271: @DocsEditable
Will there only be these annotations for classes?

https://codereview.chromium.org/15074006/diff/26001/tools/dom/scripts/dartmet...
File tools/dom/scripts/dartmetadata.py (right):

https://codereview.chromium.org/15074006/diff/26001/tools/dom/scripts/dartmet...
tools/dom/scripts/dartmetadata.py:586: def _GetSupportLevelAnnotations(self,
interface_id, member_id=None):
Please add doc comments to this method.

https://codereview.chromium.org/15074006/diff/26001/tools/dom/scripts/dartmet...
tools/dom/scripts/dartmetadata.py:589: dart_action =
support_info.get('dart_action')
What is the difference between dart_action and support_level?

https://codereview.chromium.org/15074006/diff/26001/tools/dom/scripts/dartmet...
tools/dom/scripts/dartmetadata.py:598: if dart_action:
There's a lot of duplication of code here.

Assuming everything has a support level, I would write this as:

levels = {
  'unstable' : '@Unstable',
  'experimental' : '@Experimental',
  'suppress' : '@deprecated',
  'untriaged' : '@Experimental // untriaged',
  'nonstandard' : '@Experimental // non-standard'
}

for level, value in levels:
  if level in [dart_action, support_level]:
    if comment:
      annotations.append('// %s' % comment)
    support_string = value
    if dart_action:
      support_string.append(' // %s' % support_level)
    annotations.append('%s%s' % value, support_string)

[blois, 2013-05-22 17:59:10]

https://codereview.chromium.org/15074006/diff/26001/sdk/lib/html/html_common/...
File sdk/lib/html/html_common/metadata.dart (right):

https://codereview.chromium.org/15074006/diff/26001/sdk/lib/html/html_common/...
sdk/lib/html/html_common/metadata.dart:58: * Metadata that specifies that that
member is editable through generated
On 2013/05/22 10:07:00, Andrei Mouravski wrote:
> "Annotation that specifies that a member is editable through generate files."

Wasn't this your doc comment?

https://codereview.chromium.org/15074006/diff/26001/sdk/lib/html/html_common/...
sdk/lib/html/html_common/metadata.dart:65: * Annotation which indicates that an
API is not expected to change but has
On 2013/05/22 10:07:00, Andrei Mouravski wrote:
> We need style guide for metadata doc comments...
> 
> "Annotation that..." 

Done.

https://codereview.chromium.org/15074006/diff/26001/tools/dom/scripts/dartmet...
File tools/dom/scripts/dartmetadata.py (right):

https://codereview.chromium.org/15074006/diff/26001/tools/dom/scripts/dartmet...
tools/dom/scripts/dartmetadata.py:586: def _GetSupportLevelAnnotations(self,
interface_id, member_id=None):
On 2013/05/22 10:07:00, Andrei Mouravski wrote:
> Please add doc comments to this method.

Done.

https://codereview.chromium.org/15074006/diff/26001/tools/dom/scripts/dartmet...
tools/dom/scripts/dartmetadata.py:589: dart_action =
support_info.get('dart_action')
On 2013/05/22 10:07:00, Andrei Mouravski wrote:
> What is the difference between dart_action and support_level?

support_level indicates the official status of the API (according to W3C or
WhatWG) and should be something that we could publish and get feedback on
completely independent of Dart.

dart_action is Dart's biased treatment of the API.

https://codereview.chromium.org/15074006/diff/26001/tools/dom/scripts/dartmet...
tools/dom/scripts/dartmetadata.py:598: if dart_action:
dart_actions override support_level. In later CLs, 'suppress' APIs will actually
be suppressed.

Comments were only generated for ease of review, but should be removed to
annotation (see TODO).

Unless there are bugs with this code, I'd prefer to leave as-is, since it's
still in flux.

Basically this CL is the first one actually applying the metadata and I'm trying
to keep the generated results easy to review. Later CLs need to change how we
apply the metadata, but won't require that all of the metadata be re-reviewed.


On 2013/05/22 10:07:00, Andrei Mouravski wrote:
> There's a lot of duplication of code here.
> 
> Assuming everything has a support level, I would write this as:
> 
> levels = {
>   'unstable' : '@Unstable',
>   'experimental' : '@Experimental',
>   'suppress' : '@deprecated',
>   'untriaged' : '@Experimental // untriaged',
>   'nonstandard' : '@Experimental // non-standard'
> }
> 
> for level, value in levels:
>   if level in [dart_action, support_level]:
>     if comment:
>       annotations.append('// %s' % comment)
>     support_string = value
>     if dart_action:
>       support_string.append(' // %s' % support_level)
>     annotations.append('%s%s' % value, support_string)

[blois, 2013-05-23 21:34:09]

Further feedback?

https://codereview.chromium.org/15074006/diff/26001/sdk/lib/web_sql/dartium/w...
File sdk/lib/web_sql/dartium/web_sql_dartium.dart (right):

https://codereview.chromium.org/15074006/diff/26001/sdk/lib/web_sql/dartium/w...
sdk/lib/web_sql/dartium/web_sql_dartium.dart:271: @DocsEditable
On 2013/05/22 10:07:00, Andrei Mouravski wrote:
> Will there only be these annotations for classes?

Not sure what you mean- we could add library-level experimental/deprecation, but
class-level annotations apply to all members as well (there is no such thing as
a stable member on an experimental class).

[Andrei Mouravski, 2013-05-23 21:52:12]

https://codereview.chromium.org/15074006/diff/26001/sdk/lib/web_sql/dartium/w...
File sdk/lib/web_sql/dartium/web_sql_dartium.dart (right):

https://codereview.chromium.org/15074006/diff/26001/sdk/lib/web_sql/dartium/w...
sdk/lib/web_sql/dartium/web_sql_dartium.dart:271: @DocsEditable
Actually, I was thinking more granular and have these annotations on functions
themselves, especially top level ones which don't have a class.


On 2013/05/23 21:34:10, blois wrote:
> On 2013/05/22 10:07:00, Andrei Mouravski wrote:
> > Will there only be these annotations for classes?
> 
> Not sure what you mean- we could add library-level experimental/deprecation,
but
> class-level annotations apply to all members as well (there is no such thing
as
> a stable member on an experimental class).

[Jacob, 2013-05-23 22:51:23]

lgtm

[blois, 2013-05-24 17:14:58]

Committed patchset #3 manually as r23159 (presubmit successful).