From 335a9b0c68f4304e16d5dcb31d3511528002977a Mon Sep 17 00:00:00 2001 From: Devon Carew Date: Mon, 22 Jan 2024 21:28:02 +0000 Subject: [PATCH] [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 Commit-Queue: Devon Carew --- .gitignore | 1 + DEPS | 4 ++-- sdk/lib/html/dart2js/html_dart2js.dart | 5 +++++ sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart | 5 +++++ sdk/lib/js/js.dart | 5 +++-- sdk/lib/js_interop/js_interop.dart | 8 ++++---- sdk/lib/js_util/js_util.dart | 4 ++++ sdk/lib/svg/dart2js/svg_dart2js.dart | 5 +++++ sdk/lib/web_audio/dart2js/web_audio_dart2js.dart | 5 +++++ sdk/lib/web_gl/dart2js/web_gl_dart2js.dart | 5 +++++ .../dom/templates/html/dart2js/html_dart2js.darttemplate | 5 +++++ .../html/dart2js/indexed_db_dart2js.darttemplate | 5 +++++ tools/dom/templates/html/dart2js/svg_dart2js.darttemplate | 5 +++++ .../templates/html/dart2js/web_audio_dart2js.darttemplate | 5 +++++ .../templates/html/dart2js/web_gl_dart2js.darttemplate | 5 +++++ 15 files changed, 64 insertions(+), 8 deletions(-) diff --git a/.gitignore b/.gitignore index 229fe115665..781d9dfd4f0 100644 --- a/.gitignore +++ b/.gitignore @@ -108,3 +108,4 @@ tools/xcodebuild logs/logs.json logs/results.json .dart_tool/bisect_dart/ +doc/api/ diff --git a/DEPS b/DEPS index 685d6e2554b..efd9f5693e5 100644 --- a/DEPS +++ b/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", diff --git a/sdk/lib/html/dart2js/html_dart2js.dart b/sdk/lib/html/dart2js/html_dart2js.dart index 94b522ba47d..9912e638222 100644 --- a/sdk/lib/html/dart2js/html_dart2js.dart +++ b/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, diff --git a/sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart b/sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart index 83e63d33a50..bad342008e3 100644 --- a/sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart +++ b/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 diff --git a/sdk/lib/js/js.dart b/sdk/lib/js/js.dart index 35dd0f7773e..4022c6a35dd 100644 --- a/sdk/lib/js/js.dart +++ b/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 diff --git a/sdk/lib/js_interop/js_interop.dart b/sdk/lib/js_interop/js_interop.dart index c2397dd6e09..280c3b3e624 100644 --- a/sdk/lib/js_interop/js_interop.dart +++ b/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; diff --git a/sdk/lib/js_util/js_util.dart b/sdk/lib/js_util/js_util.dart index 96e3a3e81b6..26b6f343270 100644 --- a/sdk/lib/js_util/js_util.dart +++ b/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. /// diff --git a/sdk/lib/svg/dart2js/svg_dart2js.dart b/sdk/lib/svg/dart2js/svg_dart2js.dart index b9f75739ca0..f48d2572ba8 100644 --- a/sdk/lib/svg/dart2js/svg_dart2js.dart +++ b/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/). diff --git a/sdk/lib/web_audio/dart2js/web_audio_dart2js.dart b/sdk/lib/web_audio/dart2js/web_audio_dart2js.dart index 08985ed74d2..516d96e76d0 100644 --- a/sdk/lib/web_audio/dart2js/web_audio_dart2js.dart +++ b/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; diff --git a/sdk/lib/web_gl/dart2js/web_gl_dart2js.dart b/sdk/lib/web_gl/dart2js/web_gl_dart2js.dart index f3165c313e2..8a82563244b 100644 --- a/sdk/lib/web_gl/dart2js/web_gl_dart2js.dart +++ b/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; diff --git a/tools/dom/templates/html/dart2js/html_dart2js.darttemplate b/tools/dom/templates/html/dart2js/html_dart2js.darttemplate index cd9a3e78b55..bdb041c3b54 100644 --- a/tools/dom/templates/html/dart2js/html_dart2js.darttemplate +++ b/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, diff --git a/tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate b/tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate index 1db1d5ec411..d4308bbc45b 100644 --- a/tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate +++ b/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 diff --git a/tools/dom/templates/html/dart2js/svg_dart2js.darttemplate b/tools/dom/templates/html/dart2js/svg_dart2js.darttemplate index f3724803755..ead5674084d 100644 --- a/tools/dom/templates/html/dart2js/svg_dart2js.darttemplate +++ b/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/). diff --git a/tools/dom/templates/html/dart2js/web_audio_dart2js.darttemplate b/tools/dom/templates/html/dart2js/web_audio_dart2js.darttemplate index 304ba57ed0d..2d10b837647 100644 --- a/tools/dom/templates/html/dart2js/web_audio_dart2js.darttemplate +++ b/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; diff --git a/tools/dom/templates/html/dart2js/web_gl_dart2js.darttemplate b/tools/dom/templates/html/dart2js/web_gl_dart2js.darttemplate index 08d24acf14b..155322c4d52 100644 --- a/tools/dom/templates/html/dart2js/web_gl_dart2js.darttemplate +++ b/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;