languages/dart-sdk
languages/dart-sdk
1
0
Fork 0
mirror of https://github.com/dart-lang/sdk synced 2024-10-14 11:58:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

[sdk docs] update sdk libraries to use triple slash docs

Browse source 
Change-Id: I9ee4d630763042031a06d05fb477f79deb32885b
CoreLibraryReviewExempt: dartdoc only changes, mostly to web libraries (web team reviewed)
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/288323
Commit-Queue: Devon Carew <devoncarew@google.com>
Reviewed-by: Srujan Gaddam <srujzs@google.com>
This commit is contained in:
Devon Carew 2023-03-14 19:10:25 +00:00 committed by Commit Queue
parent 107578b387
commit a548eb9bd2
16 changed files with 256 additions and 285 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
sdk/api_readme.md
View file

@ -28,4 +28,4 @@ The main site for learning and using Dart is
This API reference is automatically generated from source code in the [Dart
SDK project](https://github.com/dart-lang/sdk).
If you'd like to give feedback or edit this documentation, see
[Contributing](https://github.com/dart-lang/sdk/wiki/Contributing).
[Contributing](https://github.com/dart-lang/sdk/blob/master/CONTRIBUTING.md).

1
sdk/lib/core/core.dart
View file

@ -2,7 +2,6 @@
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
///
/// Built-in types, collections,
/// and other core functionality for every Dart program.
///

36
sdk/lib/html/dart2js/html_dart2js.dart
View file

@ -1,18 +1,16 @@
/**
* HTML elements and other resources for web-based applications that need to
* interact with the browser and the DOM (Document Object Model).
*
* This library includes DOM element types, CSS styling, local storage,
* media, speech, events, and more.
* To get started,
* check out the [Element] class, the base class for many of the HTML
* DOM types.
*
* For information on writing web apps with Dart, see https://dart.dev/web.
*
* {@category Web}
* {@canonicalFor dart:_internal.HttpStatus}
*/
/// HTML elements and other resources for web-based applications that need to
/// interact with the browser and the DOM (Document Object Model).
///
/// This library includes DOM element types, CSS styling, local storage,
/// media, speech, events, and more.
/// To get started,
/// check out the [Element] class, the base class for many of the HTML
/// DOM types.
///
/// For information on writing web apps with Dart, see https://dart.dev/web.
///
/// {@category Web}
/// {@canonicalFor dart:_internal.HttpStatus}
library dart.dom.html;
import 'dart:async';
@ -5908,7 +5906,7 @@ class _CssStyleDeclarationSet extends Object with CssStyleDeclarationBase {
// Important note: CssStyleDeclarationSet does NOT implement every method
// available in CssStyleDeclaration. Some of the methods don't make so much
// sense in terms of having a resonable value to return when you're
// sense in terms of having a reasonable value to return when you're
// considering a list of Elements. You will need to manually add any of the
// items in the MEMBERS set if you want that functionality.
}
@ -13049,7 +13047,7 @@ class Element extends Node
}
/**
* Finds all descendant elements of this element that match the specified
* Finds all descendent elements of this element that match the specified
* group of selectors.
*
* [selectors] should be a string using CSS selector syntax.
@ -23491,7 +23489,7 @@ class Node extends EventTarget {
/**
* Returns a copy of this node.
*
* If [deep] is `true`, then all of this node's children and descendents are
* If [deep] is `true`, then all of this node's children and descendants are
* copied as well. If [deep] is `false`, then only this node is copied.
*
* ## Other resources
@ -36870,7 +36868,7 @@ class _ElementCssClassSet extends CssClassSetImpl {
}
// A collection of static methods for DomTokenList. These methods are a
// work-around for the lack of annotations to express the full behaviour of
// workaround for the lack of annotations to express the full behaviour of
// the DomTokenList methods.
static DomTokenList _classListOf(Element e) => JS(

135
sdk/lib/indexed_db/dart2js/indexed_db_dart2js.dart
View file

@ -1,71 +1,68 @@
/**
* A client-side key-value store with support for indexes.
*
* Many browsers support IndexedDB&mdash;a web standard for
* an indexed database.
* By storing data on the client in an IndexedDB,
* a web app gets some advantages, such as faster performance and persistence.
* To find out which browsers support IndexedDB,
* refer to [Can I Use?](http://caniuse.com/#feat=indexeddb)
*
* In IndexedDB, each record is identified by a unique index or key,
* making data retrieval speedy.
* You can store structured data,
* such as images, arrays, and maps using IndexedDB.
* The standard does not specify size limits for individual data items
* or for the database itself, but browsers may impose storage limits.
*
* ## Using indexed_db
*
* The classes in this library provide an interface
* to the browser's IndexedDB, if it has one.
* To use this library in your code:
*
* import 'dart:indexed_db';
*
* A web app can determine if the browser supports
* IndexedDB with [IdbFactory.supported]:
*
* if (IdbFactory.supported)
* // Use indexeddb.
* else
* // Find an alternative.
*
* Access to the browser's IndexedDB is provided by the app's top-level
* [Window] object, which your code can refer to with `window.indexedDB`.
* So, for example,
* here's how to use window.indexedDB to open a database:
*
* Future open() {
* return window.indexedDB.open('myIndexedDB',
* version: 1,
* onUpgradeNeeded: _initializeDatabase)
* .then(_loadFromDB);
* }
* void _initializeDatabase(VersionChangeEvent e) {
* ...
* }
* Future _loadFromDB(Database db) {
* ...
* }
*
*
* All data in an IndexedDB is stored within an [ObjectStore].
* To manipulate the database use [Transaction]s.
*
* ## Other resources
*
* Other options for client-side data storage include:
*
* * [Window.localStorage]&mdash;a
* basic mechanism that stores data as a [Map],
* and where both the keys and the values are strings.
*
* MDN provides [API
* documentation](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).
*
* {@category Web}
*/
/// A client-side key-value store with support for indexes.
///
/// Many browsers support IndexedDB&mdash;a web standard for
/// an indexed database.
/// By storing data on the client in an IndexedDB,
/// a web app gets some advantages, such as faster performance and persistence.
/// To find out which browsers support IndexedDB,
/// refer to [Can I Use?](http://caniuse.com/#feat=indexeddb)
///
/// In IndexedDB, each record is identified by a unique index or key,
/// making data retrieval speedy.
/// You can store structured data,
/// such as images, arrays, and maps using IndexedDB.
/// The standard does not specify size limits for individual data items
/// or for the database itself, but browsers may impose storage limits.
///
/// ## Using indexed_db
///
/// The classes in this library provide an interface
/// to the browser's IndexedDB, if it has one.
/// To use this library in your code:
///
/// import 'dart:indexed_db';
///
/// A web app can determine if the browser supports
/// IndexedDB with [IdbFactory.supported]:
///
/// if (IdbFactory.supported)
/// // Use indexeddb.
/// else
/// // Find an alternative.
///
/// Access to the browser's IndexedDB is provided by the app's top-level
/// [Window] object, which your code can refer to with `window.indexedDB`.
/// So, for example,
/// here's how to use window.indexedDB to open a database:
///
/// Future open() {
/// return window.indexedDB.open('myIndexedDB',
/// version: 1,
/// onUpgradeNeeded: _initializeDatabase)
/// .then(_loadFromDB);
/// }
/// void _initializeDatabase(VersionChangeEvent e) {
/// ...
/// }
/// Future _loadFromDB(Database db) {
/// ...
/// }
///
/// All data in an IndexedDB is stored within an [ObjectStore].
/// To manipulate the database use [Transaction]s.
///
/// ## Other resources
///
/// Other options for client-side data storage include:
///
/// * [Window.localStorage]&mdash;a
/// basic mechanism that stores data as a [Map],
/// and where both the keys and the values are strings.
///
/// MDN provides [API
/// documentation](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).
///
/// {@category Web}
library dart.dom.indexed_db;
import 'dart:async';
@ -83,7 +80,7 @@ import 'dart:_js_helper' show convertDartClosureToJS;
// DO NOT EDIT - unless you are editing documentation as per:
// https://code.google.com/p/dart/wiki/ContributingHTMLDocumentation
// Auto-generated dart:svg library.
// Auto-generated dart:indexed_db library.
class _KeyRangeFactoryProvider {
static KeyRange createKeyRange_only(/*Key*/ value) =>

1
sdk/lib/isolate/isolate.dart
View file

@ -9,7 +9,6 @@
///
/// *NOTE*: The `dart:isolate` library is currently only supported by the
/// [Dart Native](https://dart.dev/overview#platform) platform.
///
/// To use this library in your code:
/// ```dart

82
sdk/lib/mirrors/mirrors.dart
View file

@ -12,48 +12,46 @@
// 'myField='. This allows us to assign unique names to getters and
// setters for the purposes of member lookup.
/**
* Basic reflection in Dart,
* with support for introspection and dynamic invocation.
*
* *Introspection* is that subset of reflection by which a running
* program can examine its own structure. For example, a function
* that prints out the names of all the members of an arbitrary object.
*
* *Dynamic invocation* refers the ability to evaluate code that
* has not been literally specified at compile time, such as calling a method
* whose name is provided as an argument (because it is looked up
* in a database, or provided interactively by the user).
*
* ## How to interpret this library's documentation
*
* As a rule, the names of Dart declarations are represented using
* instances of class [Symbol]. Whenever the doc speaks of an object *s*
* of class [Symbol] denoting a name, it means the string that
* was used to construct *s*.
*
* The documentation frequently abuses notation with
* Dart pseudo-code such as [:o.x(a):], where
* o and a are defined to be objects; what is actually meant in these
* cases is [:o'.x(a'):] where *o'* and *a'* are Dart variables
* bound to *o* and *a* respectively. Furthermore, *o'* and *a'*
* are assumed to be fresh variables (meaning that they are
* distinct from any other variables in the program).
*
* Sometimes the documentation refers to *serializable* objects.
* An object is serializable across isolates if and only if it is an instance of
* num, bool, String, a list of objects that are serializable
* across isolates, or a map with keys and values that are all serializable across
* isolates.
*
* ## Status: Unstable
*
* The dart:mirrors library is unstable and its API might change slightly as a
* result of user feedback. This library is only supported by the Dart VM and
* only available on some platforms.
*
* {@category VM}
*/
/// Basic reflection in Dart,
/// with support for introspection and dynamic invocation.
///
/// *Introspection* is that subset of reflection by which a running
/// program can examine its own structure. For example, a function
/// that prints out the names of all the members of an arbitrary object.
///
/// *Dynamic invocation* refers the ability to evaluate code that
/// has not been literally specified at compile time, such as calling a method
/// whose name is provided as an argument (because it is looked up
/// in a database, or provided interactively by the user).
///
/// ## How to interpret this library's documentation
///
/// As a rule, the names of Dart declarations are represented using
/// instances of class [Symbol]. Whenever the doc speaks of an object *s*
/// of class [Symbol] denoting a name, it means the string that
/// was used to construct *s*.
///
/// The documentation frequently abuses notation with
/// Dart pseudo-code such as [:o.x(a):], where
/// o and a are defined to be objects; what is actually meant in these
/// cases is [:o'.x(a'):] where *o'* and *a'* are Dart variables
/// bound to *o* and *a* respectively. Furthermore, *o'* and *a'*
/// are assumed to be fresh variables (meaning that they are
/// distinct from any other variables in the program).
///
/// Sometimes the documentation refers to *serializable* objects.
/// An object is serializable across isolates if and only if it is an instance of
/// num, bool, String, a list of objects that are serializable
/// across isolates, or a map with keys and values that are all serializable across
/// isolates.
///
/// ## Status: Unstable
///
/// The dart:mirrors library is unstable and its API might change slightly as a
/// result of user feedback. This library is only supported by the Dart VM and
/// only available on some platforms.
///
/// {@category VM}
library dart.mirrors;
import "dart:core";

18
sdk/lib/svg/dart2js/svg_dart2js.dart
View file

@ -1,13 +1,11 @@
/**
* Scalable Vector Graphics:
* Two-dimensional vector graphics with support for events and animation.
*
* 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/).
*
* {@category Web}
*/
/// Scalable Vector Graphics:
/// Two-dimensional vector graphics with support for events and animation.
///
/// 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/).
///
/// {@category Web}
library dart.dom.svg;
import 'dart:async';

8
sdk/lib/web_audio/dart2js/web_audio_dart2js.dart
View file

@ -1,8 +1,6 @@
/**
* High-fidelity audio programming in the browser.
*
* {@category Web}
*/
/// High-fidelity audio programming in the browser.
///
/// {@category Web}
library dart.dom.web_audio;
import 'dart:async';

8
sdk/lib/web_gl/dart2js/web_gl_dart2js.dart
View file

@ -1,8 +1,6 @@
/**
* 3D programming in the browser.
*
* {@category Web}
*/
/// 3D programming in the browser.
///
/// {@category Web}
library dart.dom.web_gl;
import 'dart:async';

26
sdk/lib/web_sql/dart2js/web_sql_dart2js.dart
View file

@ -1,16 +1,14 @@
/**
* An API for storing data in the browser that can be queried with SQL.
*
* **Caution:** this specification is no longer actively maintained by the Web
* Applications Working Group and may be removed at any time.
* See [the W3C Web SQL Database specification](http://www.w3.org/TR/webdatabase/)
* for more information.
*
* The [dart:indexed_db] APIs is a recommended alternatives.
*
* {@category Web}
* {@nodoc}
*/
/// An API for storing data in the browser that can be queried with SQL.
///
/// **Caution:** this specification is no longer actively maintained by the Web
/// Applications Working Group and may be removed at any time.
/// See [the W3C Web SQL Database specification](http://www.w3.org/TR/webdatabase/)
/// for more information.
///
/// The [dart:indexed_db] APIs is a recommended alternatives.
///
/// {@category Web}
/// {@nodoc}
library dart.dom.web_sql;
import 'dart:async';
@ -22,7 +20,7 @@ import 'dart:_foreign_helper' show JS;
import 'dart:_interceptors' show JavaScriptObject;
// DO NOT EDIT - unless you are editing documentation as per:
// https://code.google.com/p/dart/wiki/ContributingHTMLDocumentation
// Auto-generated dart:audio library.
// Auto-generated dart:web_sql library.
@deprecated
import 'dart:_js_helper'

29
tools/dom/templates/html/dart2js/html_dart2js.darttemplate
View file

@ -5,21 +5,20 @@
// DO NOT EDIT - unless you are editing documentation as per:
// https://code.google.com/p/dart/wiki/ContributingHTMLDocumentation
// Auto-generated dart:html library.
/**
* HTML elements and other resources for web-based applications that need to
* interact with the browser and the DOM (Document Object Model).
*
* This library includes DOM element types, CSS styling, local storage,
* media, speech, events, and more.
* To get started,
* check out the [Element] class, the base class for many of the HTML
* DOM types.
*
* For information on writing web apps with Dart, see https://dart.dev/web.
*
* {@category Web}
* {@canonicalFor dart:_internal.HttpStatus}
*/
/// HTML elements and other resources for web-based applications that need to
/// interact with the browser and the DOM (Document Object Model).
///
/// This library includes DOM element types, CSS styling, local storage,
/// media, speech, events, and more.
/// To get started,
/// check out the [Element] class, the base class for many of the HTML
/// DOM types.
///
/// For information on writing web apps with Dart, see https://dart.dev/web.
///
/// {@category Web}
/// {@canonicalFor dart:_internal.HttpStatus}
library dart.dom.html;
import 'dart:async';

135
tools/dom/templates/html/dart2js/indexed_db_dart2js.darttemplate
View file

@ -4,76 +4,73 @@
// DO NOT EDIT - unless you are editing documentation as per:
// https://code.google.com/p/dart/wiki/ContributingHTMLDocumentation
// Auto-generated dart:svg library.
// Auto-generated dart:indexed_db library.
/**
* A client-side key-value store with support for indexes.
*
* Many browsers support IndexedDB&mdash;a web standard for
* an indexed database.
* By storing data on the client in an IndexedDB,
* a web app gets some advantages, such as faster performance and persistence.
* To find out which browsers support IndexedDB,
* refer to [Can I Use?](http://caniuse.com/#feat=indexeddb)
*
* In IndexedDB, each record is identified by a unique index or key,
* making data retrieval speedy.
* You can store structured data,
* such as images, arrays, and maps using IndexedDB.
* The standard does not specify size limits for individual data items
* or for the database itself, but browsers may impose storage limits.
*
* ## Using indexed_db
*
* The classes in this library provide an interface
* to the browser's IndexedDB, if it has one.
* To use this library in your code:
*
* import 'dart:indexed_db';
*
* A web app can determine if the browser supports
* IndexedDB with [IdbFactory.supported]:
*
* if (IdbFactory.supported)
* // Use indexeddb.
* else
* // Find an alternative.
*
* Access to the browser's IndexedDB is provided by the app's top-level
* [Window] object, which your code can refer to with `window.indexedDB`.
* So, for example,
* here's how to use window.indexedDB to open a database:
*
* Future open() {
* return window.indexedDB.open('myIndexedDB',
* version: 1,
* onUpgradeNeeded: _initializeDatabase)
* .then(_loadFromDB);
* }
* void _initializeDatabase(VersionChangeEvent e) {
* ...
* }
* Future _loadFromDB(Database db) {
* ...
* }
*
*
* All data in an IndexedDB is stored within an [ObjectStore].
* To manipulate the database use [Transaction]s.
*
* ## Other resources
*
* Other options for client-side data storage include:
*
* * [Window.localStorage]&mdash;a
* basic mechanism that stores data as a [Map],
* and where both the keys and the values are strings.
*
* MDN provides [API
* documentation](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).
*
* {@category Web}
*/
/// A client-side key-value store with support for indexes.
///
/// Many browsers support IndexedDB&mdash;a web standard for
/// an indexed database.
/// By storing data on the client in an IndexedDB,
/// a web app gets some advantages, such as faster performance and persistence.
/// To find out which browsers support IndexedDB,
/// refer to [Can I Use?](http://caniuse.com/#feat=indexeddb)
///
/// In IndexedDB, each record is identified by a unique index or key,
/// making data retrieval speedy.
/// You can store structured data,
/// such as images, arrays, and maps using IndexedDB.
/// The standard does not specify size limits for individual data items
/// or for the database itself, but browsers may impose storage limits.
///
/// ## Using indexed_db
///
/// The classes in this library provide an interface
/// to the browser's IndexedDB, if it has one.
/// To use this library in your code:
///
/// import 'dart:indexed_db';
///
/// A web app can determine if the browser supports
/// IndexedDB with [IdbFactory.supported]:
///
/// if (IdbFactory.supported)
/// // Use indexeddb.
/// else
/// // Find an alternative.
///
/// Access to the browser's IndexedDB is provided by the app's top-level
/// [Window] object, which your code can refer to with `window.indexedDB`.
/// So, for example,
/// here's how to use window.indexedDB to open a database:
///
/// Future open() {
/// return window.indexedDB.open('myIndexedDB',
/// version: 1,
/// onUpgradeNeeded: _initializeDatabase)
/// .then(_loadFromDB);
/// }
/// void _initializeDatabase(VersionChangeEvent e) {
/// ...
/// }
/// Future _loadFromDB(Database db) {
/// ...
/// }
///
/// All data in an IndexedDB is stored within an [ObjectStore].
/// To manipulate the database use [Transaction]s.
///
/// ## Other resources
///
/// Other options for client-side data storage include:
///
/// * [Window.localStorage]&mdash;a
/// basic mechanism that stores data as a [Map],
/// and where both the keys and the values are strings.
///
/// MDN provides [API
/// documentation](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).
///
/// {@category Web}
library dart.dom.indexed_db;
import 'dart:async';

18
tools/dom/templates/html/dart2js/svg_dart2js.darttemplate
View file

@ -2,16 +2,14 @@
// https://code.google.com/p/dart/wiki/ContributingHTMLDocumentation
// Auto-generated dart:svg library.
/**
* Scalable Vector Graphics:
* Two-dimensional vector graphics with support for events and animation.
*
* 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/).
*
* {@category Web}
*/
/// Scalable Vector Graphics:
/// Two-dimensional vector graphics with support for events and animation.
///
/// 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/).
///
/// {@category Web}
library dart.dom.svg;
import 'dart:async';

8
tools/dom/templates/html/dart2js/web_audio_dart2js.darttemplate
View file

@ -2,11 +2,9 @@
// https://code.google.com/p/dart/wiki/ContributingHTMLDocumentation
// Auto-generated dart:audio library.
/**
* High-fidelity audio programming in the browser.
*
* {@category Web}
*/
/// High-fidelity audio programming in the browser.
///
/// {@category Web}
library dart.dom.web_audio;
import 'dart:async';

8
tools/dom/templates/html/dart2js/web_gl_dart2js.darttemplate
View file

@ -2,11 +2,9 @@
// https://code.google.com/p/dart/wiki/ContributingHTMLDocumentation
// Auto-generated dart:web_gl library.
/**
* 3D programming in the browser.
*
* {@category Web}
*/
/// 3D programming in the browser.
///
/// {@category Web}
library dart.dom.web_gl;
import 'dart:async';

26
tools/dom/templates/html/dart2js/web_sql_dart2js.darttemplate
View file

@ -1,20 +1,18 @@
// DO NOT EDIT - unless you are editing documentation as per:
// https://code.google.com/p/dart/wiki/ContributingHTMLDocumentation
// Auto-generated dart:audio library.
// Auto-generated dart:web_sql library.
/**
* An API for storing data in the browser that can be queried with SQL.
*
* **Caution:** this specification is no longer actively maintained by the Web
* Applications Working Group and may be removed at any time.
* See [the W3C Web SQL Database specification](http://www.w3.org/TR/webdatabase/)
* for more information.
*
* The [dart:indexed_db] APIs is a recommended alternatives.
*
* {@category Web}
* {@nodoc}
*/
/// An API for storing data in the browser that can be queried with SQL.
///
/// **Caution:** this specification is no longer actively maintained by the Web
/// Applications Working Group and may be removed at any time.
/// See [the W3C Web SQL Database specification](http://www.w3.org/TR/webdatabase/)
/// for more information.
///
/// The [dart:indexed_db] APIs is a recommended alternatives.
///
/// {@category Web}
/// {@nodoc}
@deprecated
library dart.dom.web_sql;