[docs] update the messaging for dart:html and related libraries

Change-Id: Idca54c94a583d688e3f2470f1e062e9f44f0d131
CoreLibraryReviewExempt: doc only change to the web libraries
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/347387
Reviewed-by: Srujan Gaddam <srujzs@google.com>
Commit-Queue: Devon Carew <devoncarew@google.com>

.gitignore

@@ -108,3 +108,4 @@ tools/xcodebuild
 logs/logs.json
 logs/results.json
 .dart_tool/bisect_dart/
+doc/api/

DEPS

@@ -140,7 +140,7 @@ vars = {
   #
   # For more details, see https://github.com/dart-lang/sdk/issues/30164.
   "dart_style_rev": "8b1f24a8475a0116757172cd9acca4acbf87d973", # disable rev_sdk_deps.dart
-  "dartdoc_rev": "b04c9c127fea5f3fdf600aa205f50d81d1c779c5", # https://github.com/dart-lang/dartdoc/issues/3562
+  "dartdoc_rev": "49d48d7749f48e2d9930ffda5bcde1e692ffce31",
   "ecosystem_rev": "1e2785d6900b4d709a31f4c669381dc340cad605",
   "ffi_rev": "c926657618443ff4821411ede01684096b503f84",
   "file_rev": "cd3a9324f6483f313ba1f0f3ff382ea4e6982ef2",
@@ -156,7 +156,7 @@ vars = {
   "leak_tracker_rev": "4a5b077739886f61bd6dc11c78865ef487c917c2",
   "lints_rev": "3810f8b3dc3205cfaa4ccc0054b021e68046d851",
   "logging_rev": "4d35a4e02b9237bd794378413e7ce3deb52ffcaf",
-  "markdown_rev": "7602f9f17d25702c11991380ebc7853ccdc42f7a",
+  "markdown_rev": "a8288ca3a3023228f1a8a832b78d00e11f0c4b30",
   "matcher_rev": "d9cf4f69e3f557718ab5be042dd5503afcacac51",
   "material_color_utilities_rev": "799b6ba2f3f1c28c67cc7e0b4f18e0c7d7f3c03e",
   "mime_rev": "ca9f059d2334bb2657683e0a7f5949817cb4b0e6",

sdk/lib/html/dart2js/html_dart2js.dart

@@ -1,6 +1,11 @@
 /// HTML elements and other resources for web-based applications that need to
 /// interact with the browser and the DOM (Document Object Model).
 ///
+/// > [!Note]
+/// > New projects should prefer to use
+/// > [package:web](https://pub.dev/packages/web). For existing projects, see
+/// > our [migration guide](http://dart.dev/go/package-web).
+///
 /// This library includes DOM element types, CSS styling, local storage,
 /// media, speech, events, and more.
 /// To get started,

sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart

@@ -1,5 +1,10 @@
 /// A client-side key-value store with support for indexes.
 ///
+/// > [!Note]
+/// > New projects should prefer to use
+/// > [package:web](https://pub.dev/packages/web). For existing projects, see
+/// > our [migration guide](http://dart.dev/go/package-web).
+///
 /// IndexedDB is a web standard API for client-side storage of
 /// structured data. By storing data on the client in an IndexedDB,
 /// apps can get advantages such as faster performance and

sdk/lib/js/js.dart

@@ -4,8 +4,9 @@
 
 /// Low-level support for interoperating with JavaScript.
 ///
-/// You should usually use `package:js` instead of this library. For more
-/// information, see the [JS interop page](https://dart.dev/web/js-interop).
+/// > [!Note]
+/// > You should usually use `dart:js_interop` instead of this library. For more
+/// > information, see the [JS interop page](https://dart.dev/web/js-interop).
 ///
 /// This library provides access to JavaScript objects from Dart, allowing
 /// Dart code to get and set properties, and call methods of JavaScript objects

sdk/lib/js_interop/js_interop.dart

@@ -11,10 +11,10 @@
 /// functionality like the conversion functions e.g. `toJS` and not runtime
 /// mechanisms like type checks and casts.
 ///
-/// **WARNING**:
-/// This library is still a work in progress. As such, JS types, allowed syntax,
-/// semantics, and functionality may all change, so avoid using this library in
-/// production.
+/// > [!Important]
+/// > This library is still a work in progress. As such, JS types, allowed
+/// > syntax, semantics, and functionality may all change, so avoid using this
+/// > library in production.
 ///
 /// {@category Web}
 library dart.js_interop;

sdk/lib/js_util/js_util.dart

@@ -5,6 +5,10 @@
 /// Utility methods to manipulate `package:js` annotated JavaScript interop
 /// objects in cases where the name to call is not known at runtime.
 ///
+/// > [!Note]
+/// > You should usually use `dart:js_interop` instead of this library. For more
+/// > information, see the [JS interop page](https://dart.dev/web/js-interop).
+///
 /// You should only use these methods when the same effect cannot be achieved
 /// with `@JS()` annotations.
 ///

sdk/lib/svg/dart2js/svg_dart2js.dart

@@ -1,6 +1,11 @@
 /// Scalable Vector Graphics:
 /// Two-dimensional vector graphics with support for events and animation.
 ///
+/// > [!Note]
+/// > New projects should prefer to use
+/// > [package:web](https://pub.dev/packages/web). For existing projects, see
+/// > our [migration guide](http://dart.dev/go/package-web).
+///
 /// For details about the features and syntax of SVG, a W3C standard,
 /// refer to the
 /// [Scalable Vector Graphics Specification](http://www.w3.org/TR/SVG/).

sdk/lib/web_audio/dart2js/web_audio_dart2js.dart

@@ -1,5 +1,10 @@
 /// High-fidelity audio programming in the browser.
 ///
+/// > [!Note]
+/// > New projects should prefer to use
+/// > [package:web](https://pub.dev/packages/web). For existing projects, see
+/// > our [migration guide](http://dart.dev/go/package-web).
+///
 /// {@category Web (Legacy)}
 library dart.dom.web_audio;
 

sdk/lib/web_gl/dart2js/web_gl_dart2js.dart

@@ -1,5 +1,10 @@
 /// 3D programming in the browser.
 ///
+/// > [!Note]
+/// > New projects should prefer to use
+/// > [package:web](https://pub.dev/packages/web). For existing projects, see
+/// > our [migration guide](http://dart.dev/go/package-web).
+///
 /// {@category Web (Legacy)}
 library dart.dom.web_gl;
 

tools/dom/templates/html/dart2js/html_dart2js.darttemplate

@@ -9,6 +9,11 @@
 /// HTML elements and other resources for web-based applications that need to
 /// interact with the browser and the DOM (Document Object Model).
 ///
+/// > [!Note]
+/// > New projects should prefer to use
+/// > [package:web](https://pub.dev/packages/web). For existing projects, see
+/// > our [migration guide](http://dart.dev/go/package-web).
+///
 /// This library includes DOM element types, CSS styling, local storage,
 /// media, speech, events, and more.
 /// To get started,

tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate

@@ -8,6 +8,11 @@
 
 /// A client-side key-value store with support for indexes.
 ///
+/// > [!Note]
+/// > New projects should prefer to use
+/// > [package:web](https://pub.dev/packages/web). For existing projects, see
+/// > our [migration guide](http://dart.dev/go/package-web).
+///
 /// IndexedDB is a web standard API for client-side storage of
 /// structured data. By storing data on the client in an IndexedDB,
 /// apps can get advantages such as faster performance and

tools/dom/templates/html/dart2js/svg_dart2js.darttemplate

@@ -5,6 +5,11 @@
 /// Scalable Vector Graphics:
 /// Two-dimensional vector graphics with support for events and animation.
 ///
+/// > [!Note]
+/// > New projects should prefer to use
+/// > [package:web](https://pub.dev/packages/web). For existing projects, see
+/// > our [migration guide](http://dart.dev/go/package-web).
+///
 /// For details about the features and syntax of SVG, a W3C standard,
 /// refer to the
 /// [Scalable Vector Graphics Specification](http://www.w3.org/TR/SVG/).

tools/dom/templates/html/dart2js/web_audio_dart2js.darttemplate

@@ -4,6 +4,11 @@
 
 /// High-fidelity audio programming in the browser.
 ///
+/// > [!Note]
+/// > New projects should prefer to use
+/// > [package:web](https://pub.dev/packages/web). For existing projects, see
+/// > our [migration guide](http://dart.dev/go/package-web).
+///
 /// {@category Web (Legacy)}
 library dart.dom.web_audio;
 

tools/dom/templates/html/dart2js/web_gl_dart2js.darttemplate

@@ -4,6 +4,11 @@
 
 /// 3D programming in the browser.
 ///
+/// > [!Note]
+/// > New projects should prefer to use
+/// > [package:web](https://pub.dev/packages/web). For existing projects, see
+/// > our [migration guide](http://dart.dev/go/package-web).
+///
 /// {@category Web (Legacy)}
 library dart.dom.web_gl;