[dart2js js_runtime] Run dartfmt --fix-doc-comments
TBR=sigmund@google.com
Change-Id: If2e9a8d7a632ded60cf5cac54c32cac96f472d8e
Reviewed-on: https://dart-review.googlesource.com/c/89169
Reviewed-by: Stephen Adams <sra@google.com>
Commit-Queue: Stephen Adams <sra@google.com>
diff --git a/sdk/lib/_internal/js_runtime/lib/convert_patch.dart b/sdk/lib/_internal/js_runtime/lib/convert_patch.dart
index afb5062..a8dcc31 100644
--- a/sdk/lib/_internal/js_runtime/lib/convert_patch.dart
+++ b/sdk/lib/_internal/js_runtime/lib/convert_patch.dart
@@ -11,22 +11,20 @@
import 'dart:collection' show LinkedHashMap, MapBase;
import 'dart:_native_typed_data' show NativeUint8List;
-/**
- * Parses [json] and builds the corresponding parsed JSON value.
- *
- * Parsed JSON values Nare of the types [num], [String], [bool], [Null],
- * [List]s of parsed JSON values or [Map]s from [String] to parsed
- * JSON values.
- *
- * The optional [reviver] function, if provided, is called once for each object
- * or list property parsed. The arguments are the property name ([String]) or
- * list index ([int]), and the value is the parsed value. The return value of
- * the reviver will be used as the value of that property instead of the parsed
- * value. The top level value is passed to the reviver with the empty string as
- * a key.
- *
- * Throws [FormatException] if the input is not valid JSON text.
- */
+/// Parses [json] and builds the corresponding parsed JSON value.
+///
+/// Parsed JSON values Nare of the types [num], [String], [bool], [Null],
+/// [List]s of parsed JSON values or [Map]s from [String] to parsed
+/// JSON values.
+///
+/// The optional [reviver] function, if provided, is called once for each object
+/// or list property parsed. The arguments are the property name ([String]) or
+/// list index ([int]), and the value is the parsed value. The return value of
+/// the reviver will be used as the value of that property instead of the parsed
+/// value. The top level value is passed to the reviver with the empty string
+/// as a key.
+///
+/// Throws [FormatException] if the input is not valid JSON text.
@patch
_parseJson(String source, reviver(key, value)) {
if (source is! String) throw argumentErrorValue(source);
@@ -46,11 +44,9 @@
}
}
-/**
- * Walks the raw JavaScript value [json], replacing JavaScript Objects with
- * Maps. [json] is expected to be freshly allocated so elements can be replaced
- * in-place.
- */
+/// Walks the raw JavaScript value [json], replacing JavaScript Objects with
+/// Maps. [json] is expected to be freshly allocated so elements can be replaced
+/// in-place.
_convertJsonToDart(json, reviver(key, value)) {
assert(reviver != null);
walk(e) {
@@ -365,12 +361,10 @@
}
}
-/**
- * Implements the chunked conversion from a JSON string to its corresponding
- * object.
- *
- * The sink only creates one object, but its input can be chunked.
- */
+/// Implements the chunked conversion from a JSON string to its corresponding
+/// object.
+///
+/// The sink only creates one object, but its input can be chunked.
// TODO(floitsch): don't accumulate everything before starting to decode.
class _JsonDecoderSink extends _StringSinkConversionSink {
final _Reviver _reviver;
diff --git a/sdk/lib/_internal/js_runtime/lib/core_patch.dart b/sdk/lib/_internal/js_runtime/lib/core_patch.dart
index 2d0f531..27d7d25 100644
--- a/sdk/lib/_internal/js_runtime/lib/core_patch.dart
+++ b/sdk/lib/_internal/js_runtime/lib/core_patch.dart
@@ -685,11 +685,9 @@
// are not encoded by any encoding table.
static final RegExp _needsNoEncoding = new RegExp(r'^[\-\.0-9A-Z_a-z~]*$');
- /**
- * This is the internal implementation of JavaScript's encodeURI function.
- * It encodes all characters in the string [text] except for those
- * that appear in [canonicalTable], and returns the escaped string.
- */
+ /// This is the internal implementation of JavaScript's encodeURI function.
+ /// It encodes all characters in the string [text] except for those
+ /// that appear in [canonicalTable], and returns the escaped string.
@patch
static String _uriEncode(List<int> canonicalTable, String text,
Encoding encoding, bool spaceToPlus) {
@@ -879,12 +877,10 @@
* and disclaimer.
*/
-/**
- * An implementation for the arbitrarily large integer.
- *
- * The integer number is represented by a sign, an array of 16-bit unsigned
- * integers in little endian format, and a number of used digits in that array.
- */
+/// An implementation for the arbitrarily large integer.
+///
+/// The integer number is represented by a sign, an array of 16-bit unsigned
+/// integers in little endian format, and a number of used digits in that array.
class _BigIntImpl implements BigInt {
// Bits per digit.
static const int _digitBits = 16;
@@ -925,29 +921,27 @@
/// replaced.
final int _used;
- /**
- * Parses [source] as a, possibly signed, integer literal and returns its
- * value.
- *
- * The [source] must be a non-empty sequence of base-[radix] digits,
- * optionally prefixed with a minus or plus sign ('-' or '+').
- *
- * The [radix] must be in the range 2..36. The digits used are
- * first the decimal digits 0..9, and then the letters 'a'..'z' with
- * values 10 through 35. Also accepts upper-case letters with the same
- * values as the lower-case ones.
- *
- * If no [radix] is given then it defaults to 10. In this case, the [source]
- * digits may also start with `0x`, in which case the number is interpreted
- * as a hexadecimal literal, which effectively means that the `0x` is ignored
- * and the radix is instead set to 16.
- *
- * For any int `n` and radix `r`, it is guaranteed that
- * `n == int.parse(n.toRadixString(r), radix: r)`.
- *
- * Throws a [FormatException] if the [source] is not a valid integer literal,
- * optionally prefixed by a sign.
- */
+ /// Parses [source] as a, possibly signed, integer literal and returns its
+ /// value.
+ ///
+ /// The [source] must be a non-empty sequence of base-[radix] digits,
+ /// optionally prefixed with a minus or plus sign ('-' or '+').
+ ///
+ /// The [radix] must be in the range 2..36. The digits used are
+ /// first the decimal digits 0..9, and then the letters 'a'..'z' with
+ /// values 10 through 35. Also accepts upper-case letters with the same
+ /// values as the lower-case ones.
+ ///
+ /// If no [radix] is given then it defaults to 10. In this case, the [source]
+ /// digits may also start with `0x`, in which case the number is interpreted
+ /// as a hexadecimal literal, which effectively means that the `0x` is ignored
+ /// and the radix is instead set to 16.
+ ///
+ /// For any int `n` and radix `r`, it is guaranteed that
+ /// `n == int.parse(n.toRadixString(r), radix: r)`.
+ ///
+ /// Throws a [FormatException] if the [source] is not a valid integer literal,
+ /// optionally prefixed by a sign.
static _BigIntImpl parse(String source, {int radix}) {
var result = _tryParse(source, radix: radix);
if (result == null) {
@@ -1233,22 +1227,18 @@
return absResult;
}
- /**
- * Return the negative value of this integer.
- *
- * The result of negating an integer always has the opposite sign, except
- * for zero, which is its own negation.
- */
+ /// Return the negative value of this integer.
+ ///
+ /// The result of negating an integer always has the opposite sign, except
+ /// for zero, which is its own negation.
_BigIntImpl operator -() {
if (_used == 0) return this;
return new _BigIntImpl._(!_isNegative, _used, _digits);
}
- /**
- * Returns the absolute value of this integer.
- *
- * For any integer `x`, the result is the same as `x < 0 ? -x : x`.
- */
+ /// Returns the absolute value of this integer.
+ ///
+ /// For any integer `x`, the result is the same as `x < 0 ? -x : x`.
_BigIntImpl abs() => _isNegative ? -this : this;
/// Returns this << n *_DIGIT_BITS.
@@ -1338,18 +1328,16 @@
resultDigits[digitShift] = carry;
}
- /**
- * Shift the bits of this integer to the left by [shiftAmount].
- *
- * Shifting to the left makes the number larger, effectively multiplying
- * the number by `pow(2, shiftIndex)`.
- *
- * There is no limit on the size of the result. It may be relevant to
- * limit intermediate values by using the "and" operator with a suitable
- * mask.
- *
- * It is an error if [shiftAmount] is negative.
- */
+ /// Shift the bits of this integer to the left by [shiftAmount].
+ ///
+ /// Shifting to the left makes the number larger, effectively multiplying
+ /// the number by `pow(2, shiftIndex)`.
+ ///
+ /// There is no limit on the size of the result. It may be relevant to
+ /// limit intermediate values by using the "and" operator with a suitable
+ /// mask.
+ ///
+ /// It is an error if [shiftAmount] is negative.
_BigIntImpl operator <<(int shiftAmount) {
if (shiftAmount < 0) {
throw new ArgumentError("shift-amount must be posititve $shiftAmount");
@@ -1405,15 +1393,13 @@
resultDigits[last] = carry;
}
- /**
- * Shift the bits of this integer to the right by [shiftAmount].
- *
- * Shifting to the right makes the number smaller and drops the least
- * significant bits, effectively doing an integer division by
- *`pow(2, shiftIndex)`.
- *
- * It is an error if [shiftAmount] is negative.
- */
+ /// Shift the bits of this integer to the right by [shiftAmount].
+ ///
+ /// Shifting to the right makes the number smaller and drops the least
+ /// significant bits, effectively doing an integer division by
+ /// `pow(2, shiftIndex)`.
+ ///
+ /// It is an error if [shiftAmount] is negative.
_BigIntImpl operator >>(int shiftAmount) {
if (shiftAmount < 0) {
throw new ArgumentError("shift-amount must be posititve $shiftAmount");
@@ -1456,12 +1442,10 @@
return _compareDigits(_digits, _used, other._digits, other._used);
}
- /**
- * Compares this to `other`.
- *
- * Returns a negative number if `this` is less than `other`, zero if they are
- * equal, and a positive number if `this` is greater than `other`.
- */
+ /// Compares this to `other`.
+ ///
+ /// Returns a negative number if `this` is less than `other`, zero if they are
+ /// equal, and a positive number if `this` is greater than `other`.
int compareTo(BigInt bigInt) {
_BigIntImpl other = bigInt;
if (_isNegative == other._isNegative) {
@@ -1649,16 +1633,14 @@
return new _BigIntImpl._(isNegative, resultUsed, resultDigits);
}
- /**
- * Bit-wise and operator.
- *
- * Treating both `this` and [other] as sufficiently large two's component
- * integers, the result is a number with only the bits set that are set in
- * both `this` and [other]
- *
- * Of both operands are negative, the result is negative, otherwise
- * the result is non-negative.
- */
+ /// Bit-wise and operator.
+ ///
+ /// Treating both `this` and [other] as sufficiently large two's component
+ /// integers, the result is a number with only the bits set that are set in
+ /// both `this` and [other]
+ ///
+ /// Of both operands are negative, the result is negative, otherwise
+ /// the result is non-negative.
_BigIntImpl operator &(BigInt bigInt) {
_BigIntImpl other = bigInt;
if (_isZero || other._isZero) return zero;
@@ -1689,16 +1671,14 @@
return p._absAndNotSetSign(n1, false);
}
- /**
- * Bit-wise or operator.
- *
- * Treating both `this` and [other] as sufficiently large two's component
- * integers, the result is a number with the bits set that are set in either
- * of `this` and [other]
- *
- * If both operands are non-negative, the result is non-negative,
- * otherwise the result us negative.
- */
+ /// Bit-wise or operator.
+ ///
+ /// Treating both `this` and [other] as sufficiently large two's component
+ /// integers, the result is a number with the bits set that are set in either
+ /// of `this` and [other]
+ ///
+ /// If both operands are non-negative, the result is non-negative,
+ /// otherwise the result us negative.
_BigIntImpl operator |(BigInt bigInt) {
_BigIntImpl other = bigInt;
if (_isZero) return other;
@@ -1731,16 +1711,14 @@
return n1._absAndNotSetSign(p, true)._absAddSetSign(one, true);
}
- /**
- * Bit-wise exclusive-or operator.
- *
- * Treating both `this` and [other] as sufficiently large two's component
- * integers, the result is a number with the bits set that are set in one,
- * but not both, of `this` and [other]
- *
- * If the operands have the same sign, the result is non-negative,
- * otherwise the result is negative.
- */
+ /// Bit-wise exclusive-or operator.
+ ///
+ /// Treating both `this` and [other] as sufficiently large two's component
+ /// integers, the result is a number with the bits set that are set in one,
+ /// but not both, of `this` and [other]
+ ///
+ /// If the operands have the same sign, the result is non-negative,
+ /// otherwise the result is negative.
_BigIntImpl operator ^(BigInt bigInt) {
_BigIntImpl other = bigInt;
if (_isZero) return other;
@@ -1770,14 +1748,12 @@
return p._absXorSetSign(n1, true)._absAddSetSign(one, true);
}
- /**
- * The bit-wise negate operator.
- *
- * Treating `this` as a sufficiently large two's component integer,
- * the result is a number with the opposite bits set.
- *
- * This maps any integer `x` to `-x - 1`.
- */
+ /// The bit-wise negate operator.
+ ///
+ /// Treating `this` as a sufficiently large two's component integer,
+ /// the result is a number with the opposite bits set.
+ ///
+ /// This maps any integer `x` to `-x - 1`.
_BigIntImpl operator ~() {
if (_isZero) return _minusOne;
if (_isNegative) {
@@ -2073,65 +2049,59 @@
return finish(hash);
}
- /**
- * Test whether this value is numerically equal to `other`.
- *
- * If [other] is a [_BigIntImpl] returns whether the two operands have the same
- * value.
- *
- * Returns false if `other` is not a [_BigIntImpl].
- */
+ /// Test whether this value is numerically equal to `other`.
+ ///
+ /// If [other] is a [_BigIntImpl] returns whether the two operands have the
+ /// same value.
+ ///
+ /// Returns false if `other` is not a [_BigIntImpl].
bool operator ==(Object other) =>
other is _BigIntImpl && compareTo(other) == 0;
- /**
- * Returns the minimum number of bits required to store this big integer.
- *
- * The number of bits excludes the sign bit, which gives the natural length
- * for non-negative (unsigned) values. Negative values are complemented to
- * return the bit position of the first bit that differs from the sign bit.
- *
- * To find the number of bits needed to store the value as a signed value,
- * add one, i.e. use `x.bitLength + 1`.
- *
- * ```
- * x.bitLength == (-x-1).bitLength
- *
- * new BigInt.from(3).bitLength == 2; // 00000011
- * new BigInt.from(2).bitLength == 2; // 00000010
- * new BigInt.from(1).bitLength == 1; // 00000001
- * new BigInt.from(0).bitLength == 0; // 00000000
- * new BigInt.from(-1).bitLength == 0; // 11111111
- * new BigInt.from(-2).bitLength == 1; // 11111110
- * new BigInt.from(-3).bitLength == 2; // 11111101
- * new BigInt.from(-4).bitLength == 2; // 11111100
- * ```
- */
+ /// Returns the minimum number of bits required to store this big integer.
+ ///
+ /// The number of bits excludes the sign bit, which gives the natural length
+ /// for non-negative (unsigned) values. Negative values are complemented to
+ /// return the bit position of the first bit that differs from the sign bit.
+ ///
+ /// To find the number of bits needed to store the value as a signed value,
+ /// add one, i.e. use `x.bitLength + 1`.
+ ///
+ /// ```
+ /// x.bitLength == (-x-1).bitLength
+ ///
+ /// new BigInt.from(3).bitLength == 2; // 00000011
+ /// new BigInt.from(2).bitLength == 2; // 00000010
+ /// new BigInt.from(1).bitLength == 1; // 00000001
+ /// new BigInt.from(0).bitLength == 0; // 00000000
+ /// new BigInt.from(-1).bitLength == 0; // 11111111
+ /// new BigInt.from(-2).bitLength == 1; // 11111110
+ /// new BigInt.from(-3).bitLength == 2; // 11111101
+ /// new BigInt.from(-4).bitLength == 2; // 11111100
+ /// ```
int get bitLength {
if (_used == 0) return 0;
if (_isNegative) return (~this).bitLength;
return _digitBits * (_used - 1) + _digits[_used - 1].bitLength;
}
- /**
- * Truncating division operator.
- *
- * Performs a truncating integer division, where the remainder is discarded.
- *
- * The remainder can be computed using the [remainder] method.
- *
- * Examples:
- * ```
- * var seven = new BigInt.from(7);
- * var three = new BigInt.from(3);
- * seven ~/ three; // => 2
- * (-seven) ~/ three; // => -2
- * seven ~/ -three; // => -2
- * seven.remainder(three); // => 1
- * (-seven).remainder(three); // => -1
- * seven.remainder(-three); // => 1
- * ```
- */
+ /// Truncating division operator.
+ ///
+ /// Performs a truncating integer division, where the remainder is discarded.
+ ///
+ /// The remainder can be computed using the [remainder] method.
+ ///
+ /// Examples:
+ /// ```
+ /// var seven = new BigInt.from(7);
+ /// var three = new BigInt.from(3);
+ /// seven ~/ three; // => 2
+ /// (-seven) ~/ three; // => -2
+ /// seven ~/ -three; // => -2
+ /// seven.remainder(three); // => 1
+ /// (-seven).remainder(three); // => -1
+ /// seven.remainder(-three); // => 1
+ /// ```
_BigIntImpl operator ~/(BigInt bigInt) {
_BigIntImpl other = bigInt;
if (other._used == 0) {
@@ -2140,13 +2110,12 @@
return _div(other);
}
- /**
- * Returns the remainder of the truncating division of `this` by [other].
- *
- * The result `r` of this operation satisfies:
- * `this == (this ~/ other) * other + r`.
- * As a consequence the remainder `r` has the same sign as the divider `this`.
- */
+ /// Returns the remainder of the truncating division of `this` by [other].
+ ///
+ /// The result `r` of this operation satisfies:
+ /// `this == (this ~/ other) * other + r`.
+ /// As a consequence the remainder `r` has the same sign as the divider
+ /// `this`.
_BigIntImpl remainder(BigInt bigInt) {
_BigIntImpl other = bigInt;
if (other._used == 0) {
@@ -2158,29 +2127,27 @@
/// Division operator.
double operator /(BigInt other) => this.toDouble() / other.toDouble();
- /** Relational less than operator. */
+ /// Relational less than operator.
bool operator <(BigInt other) => compareTo(other) < 0;
- /** Relational less than or equal operator. */
+ /// Relational less than or equal operator.
bool operator <=(BigInt other) => compareTo(other) <= 0;
- /** Relational greater than operator. */
+ /// Relational greater than operator.
bool operator >(BigInt other) => compareTo(other) > 0;
- /** Relational greater than or equal operator. */
+ /// Relational greater than or equal operator.
bool operator >=(BigInt other) => compareTo(other) >= 0;
- /**
- * Euclidean modulo operator.
- *
- * Returns the remainder of the Euclidean division. The Euclidean division of
- * two integers `a` and `b` yields two integers `q` and `r` such that
- * `a == b * q + r` and `0 <= r < b.abs()`.
- *
- * The sign of the returned value `r` is always positive.
- *
- * See [remainder] for the remainder of the truncating division.
- */
+ /// Euclidean modulo operator.
+ ///
+ /// Returns the remainder of the Euclidean division. The Euclidean division of
+ /// two integers `a` and `b` yields two integers `q` and `r` such that
+ /// `a == b * q + r` and `0 <= r < b.abs()`.
+ ///
+ /// The sign of the returned value `r` is always positive.
+ ///
+ /// See [remainder] for the remainder of the truncating division.
_BigIntImpl operator %(BigInt bigInt) {
_BigIntImpl other = bigInt;
if (other._used == 0) {
@@ -2197,12 +2164,10 @@
return result;
}
- /**
- * Returns the sign of this big integer.
- *
- * Returns 0 for zero, -1 for values less than zero and
- * +1 for values greater than zero.
- */
+ /// Returns the sign of this big integer.
+ ///
+ /// Returns 0 for zero, -1 for values less than zero and
+ /// +1 for values greater than zero.
int get sign {
if (_used == 0) return 0;
return _isNegative ? -1 : 1;
@@ -2239,12 +2204,10 @@
return result;
}
- /**
- * Returns this integer to the power of [exponent] modulo [modulus].
- *
- * The [exponent] must be non-negative and [modulus] must be
- * positive.
- */
+ /// Returns this integer to the power of [exponent] modulo [modulus].
+ ///
+ /// The [exponent] must be non-negative and [modulus] must be
+ /// positive.
_BigIntImpl modPow(BigInt bigExponent, BigInt bigModulus) {
_BigIntImpl exponent = bigExponent;
_BigIntImpl modulus = bigModulus;
@@ -2537,14 +2500,12 @@
return new _BigIntImpl._(false, maxUsed, dDigits);
}
- /**
- * Returns the modular multiplicative inverse of this big integer
- * modulo [modulus].
- *
- * The [modulus] must be positive.
- *
- * It is an error if no modular inverse exists.
- */
+ /// Returns the modular multiplicative inverse of this big integer
+ /// modulo [modulus].
+ ///
+ /// The [modulus] must be positive.
+ ///
+ /// It is an error if no modular inverse exists.
// Returns 1/this % modulus, with modulus > 0.
_BigIntImpl modInverse(BigInt bigInt) {
_BigIntImpl modulus = bigInt;
@@ -2559,19 +2520,17 @@
return _binaryGcd(modulus, tmp, true);
}
- /**
- * Returns the greatest common divisor of this big integer and [other].
- *
- * If either number is non-zero, the result is the numerically greatest
- * integer dividing both `this` and `other`.
- *
- * The greatest common divisor is independent of the order,
- * so `x.gcd(y)` is always the same as `y.gcd(x)`.
- *
- * For any integer `x`, `x.gcd(x)` is `x.abs()`.
- *
- * If both `this` and `other` is zero, the result is also zero.
- */
+ /// Returns the greatest common divisor of this big integer and [other].
+ ///
+ /// If either number is non-zero, the result is the numerically greatest
+ /// integer dividing both `this` and `other`.
+ ///
+ /// The greatest common divisor is independent of the order,
+ /// so `x.gcd(y)` is always the same as `y.gcd(x)`.
+ ///
+ /// For any integer `x`, `x.gcd(x)` is `x.abs()`.
+ ///
+ /// If both `this` and `other` is zero, the result is also zero.
_BigIntImpl gcd(BigInt bigInt) {
_BigIntImpl other = bigInt;
if (_isZero) return other.abs();
@@ -2579,70 +2538,67 @@
return _binaryGcd(this, other, false);
}
- /**
- * Returns the least significant [width] bits of this big integer as a
- * non-negative number (i.e. unsigned representation). The returned value has
- * zeros in all bit positions higher than [width].
- *
- * ```
- * new BigInt.from(-1).toUnsigned(5) == 31 // 11111111 -> 00011111
- * ```
- *
- * This operation can be used to simulate arithmetic from low level languages.
- * For example, to increment an 8 bit quantity:
- *
- * ```
- * q = (q + 1).toUnsigned(8);
- * ```
- *
- * `q` will count from `0` up to `255` and then wrap around to `0`.
- *
- * If the input fits in [width] bits without truncation, the result is the
- * same as the input. The minimum width needed to avoid truncation of `x` is
- * given by `x.bitLength`, i.e.
- *
- * ```
- * x == x.toUnsigned(x.bitLength);
- * ```
- */
+ /// Returns the least significant [width] bits of this big integer as a
+ /// non-negative number (i.e. unsigned representation). The returned value
+ /// has zeros in all bit positions higher than [width].
+ ///
+ /// ```
+ /// new BigInt.from(-1).toUnsigned(5) == 31 // 11111111 -> 00011111
+ /// ```
+ ///
+ /// This operation can be used to simulate arithmetic from low level
+ /// languages. For example, to increment an 8 bit quantity:
+ ///
+ /// ```
+ /// q = (q + 1).toUnsigned(8);
+ /// ```
+ ///
+ /// `q` will count from `0` up to `255` and then wrap around to `0`.
+ ///
+ /// If the input fits in [width] bits without truncation, the result is the
+ /// same as the input. The minimum width needed to avoid truncation of `x` is
+ /// given by `x.bitLength`, i.e.
+ ///
+ /// ```
+ /// x == x.toUnsigned(x.bitLength);
+ /// ```
_BigIntImpl toUnsigned(int width) {
return this & ((one << width) - one);
}
- /**
- * Returns the least significant [width] bits of this integer, extending the
- * highest retained bit to the sign. This is the same as truncating the value
- * to fit in [width] bits using an signed 2-s complement representation. The
- * returned value has the same bit value in all positions higher than [width].
- *
- * ```
- * var big15 = new BigInt.from(15);
- * var big16 = new BigInt.from(16);
- * var big239 = new BigInt.from(239);
- * V--sign bit-V
- * big16.toSigned(5) == -big16 // 00010000 -> 11110000
- * big239.toSigned(5) == big15 // 11101111 -> 00001111
- * ^ ^
- * ```
- *
- * This operation can be used to simulate arithmetic from low level languages.
- * For example, to increment an 8 bit signed quantity:
- *
- * ```
- * q = (q + 1).toSigned(8);
- * ```
- *
- * `q` will count from `0` up to `127`, wrap to `-128` and count back up to
- * `127`.
- *
- * If the input value fits in [width] bits without truncation, the result is
- * the same as the input. The minimum width needed to avoid truncation of `x`
- * is `x.bitLength + 1`, i.e.
- *
- * ```
- * x == x.toSigned(x.bitLength + 1);
- * ```
- */
+ /// Returns the least significant [width] bits of this integer, extending the
+ /// highest retained bit to the sign. This is the same as truncating the
+ /// value to fit in [width] bits using an signed 2-s complement
+ /// representation. The returned value has the same bit value in all
+ /// positions higher than [width].
+ ///
+ /// ```
+ /// var big15 = new BigInt.from(15);
+ /// var big16 = new BigInt.from(16);
+ /// var big239 = new BigInt.from(239);
+ /// V--sign bit-V
+ /// big16.toSigned(5) == -big16 // 00010000 -> 11110000
+ /// big239.toSigned(5) == big15 // 11101111 -> 00001111
+ /// ^ ^
+ /// ```
+ ///
+ /// This operation can be used to simulate arithmetic from low level
+ /// languages. For example, to increment an 8 bit signed quantity:
+ ///
+ /// ```
+ /// q = (q + 1).toSigned(8);
+ /// ```
+ ///
+ /// `q` will count from `0` up to `127`, wrap to `-128` and count back up to
+ /// `127`.
+ ///
+ /// If the input value fits in [width] bits without truncation, the result is
+ /// the same as the input. The minimum width needed to avoid truncation of
+ /// `x` is `x.bitLength + 1`, i.e.
+ ///
+ /// ```
+ /// x == x.toSigned(x.bitLength + 1);
+ /// ```
_BigIntImpl toSigned(int width) {
// The value of binary number weights each bit by a power of two. The
// twos-complement value weights the sign bit negatively. We compute the
@@ -2671,13 +2627,11 @@
return _isNegative ? -result : result;
}
- /**
- * Returns this [_BigIntImpl] as a [double].
- *
- * If the number is not representable as a [double], an
- * approximation is returned. For numerically large integers, the
- * approximation may be infinite.
- */
+ /// Returns this [_BigIntImpl] as a [double].
+ ///
+ /// If the number is not representable as a [double], an
+ /// approximation is returned. For numerically large integers, the
+ /// approximation may be infinite.
double toDouble() {
const int exponentBias = 1075;
// There are 11 bits for the exponent.
@@ -2773,13 +2727,11 @@
return resultBits.buffer.asByteData().getFloat64(0, Endian.little);
}
- /**
- * Returns a String-representation of this integer.
- *
- * The returned string is parsable by [parse].
- * For any `_BigIntImpl` `i`, it is guaranteed that
- * `i == _BigIntImpl.parse(i.toString())`.
- */
+ /// Returns a String-representation of this integer.
+ ///
+ /// The returned string is parsable by [parse].
+ /// For any `_BigIntImpl` `i`, it is guaranteed that
+ /// `i == _BigIntImpl.parse(i.toString())`.
String toString() {
if (_used == 0) return "0";
if (_used == 1) {
@@ -2811,14 +2763,12 @@
return _a + digit - 10;
}
- /**
- * Converts [this] to a string representation in the given [radix].
- *
- * In the string representation, lower-case letters are used for digits above
- * '9', with 'a' being 10 an 'z' being 35.
- *
- * The [radix] argument must be an integer in the range 2 to 36.
- */
+ /// Converts [this] to a string representation in the given [radix].
+ ///
+ /// In the string representation, lower-case letters are used for digits above
+ /// '9', with 'a' being 10 an 'z' being 35.
+ ///
+ /// The [radix] argument must be an integer in the range 2 to 36.
String toRadixString(int radix) {
if (radix > 36) throw new RangeError.range(radix, 2, 36);
diff --git a/sdk/lib/_internal/js_runtime/lib/foreign_helper.dart b/sdk/lib/_internal/js_runtime/lib/foreign_helper.dart
index 4f549a0..5377630 100644
--- a/sdk/lib/_internal/js_runtime/lib/foreign_helper.dart
+++ b/sdk/lib/_internal/js_runtime/lib/foreign_helper.dart
@@ -6,152 +6,151 @@
import 'dart:_js_embedded_names' show JsGetName, JsBuiltin;
-/**
- * Emits a JavaScript code fragment parametrized by arguments.
- *
- * Hash characters `#` in the [codeTemplate] are replaced in left-to-right order
- * with expressions that contain the values of, or evaluate to, the arguments.
- * The number of hash marks must match the number or arguments. Although
- * declared with arguments [arg0] through [arg2], the form actually has no limit
- * on the number of arguments.
- *
- * The [typeDescription] argument is interpreted as a description of the
- * behavior of the JavaScript code. Currently it describes the side effects
- * types that may be returned by the expression, with the additional behavior
- * that the returned values may be fresh instances of the types. The type
- * information must be correct as it is trusted by the compiler in
- * optimizations, and it must be precise as possible since it is used for native
- * live type analysis to tree-shake large parts of the DOM libraries. If poorly
- * written, the [typeDescription] will cause unnecessarily bloated programs.
- * (You can check for this by compiling with `--verbose`; there is an info
- * message describing the number of native (DOM) types that can be removed,
- * which usually should be greater than zero.)
- *
- * The [typeDescription] must be a [String]. Two forms of it are supported:
- *
- * 1) a union of types separated by vertical bar `|` symbols, e.g.
- * `"num|String"` describes the union of numbers and Strings. There is no
- * type in Dart that is this precise. The Dart alternative would be `Object`
- * or `dynamic`, but these types imply that the JS-code might also be
- * creating instances of all the DOM types.
- *
- * If `null` is possible, it must be specified explicitly, e.g.
- * `"String|Null"`. [typeDescription] has several extensions to help describe
- * the behavior more accurately. In addition to the union type already
- * described:
- *
- * + `=Object` is a plain JavaScript object. Some DOM methods return
- * instances that have no corresponding Dart type (e.g. cross-frame
- * documents), `=Object` can be used to describe these untyped' values.
- *
- * + `var` or empty string. If the entire [typeDescription] is `var` (or
- * empty string) then the type is `dynamic` but the code is known to not
- * create any instances.
- *
- * Examples:
- *
- * // Parent window might be an opaque cross-frame window.
- * var thing = JS('=Object|Window', '#.parent', myWindow);
- *
- * 2) a sequence of the form `<tag>:<value>;` where `<tag>` is one of
- * `creates`, `returns`, `effects` or `depends`.
- *
- * The first two tags are used to specify the created and returned types of
- * the expression. The value of `creates` and `returns` is a type string as
- * defined in 1).
- *
- * The tags `effects` and `depends` encode the side effects of this call.
- * They can be omitted, in which case the expression is parsed and a safe
- * conservative side-effect estimation is computed.
- *
- * The values of `effects` and `depends` may be 'all', 'none' or a
- * comma-separated list of 'no-index', 'no-instance' and 'no-static'.
- *
- * The value 'all' indicates that the call affects/depends on every
- * side-effect. The flag 'none' signals that the call does not affect
- * (resp. depends on) anything.
- *
- * The value 'no-index' indicates that the call does *not* do (resp. depends
- * on) any array index-store. The flag 'no-instance' indicates that the call
- * does not modify (resp. depends on) any instance variable. Similarly,
- * the 'no-static' value indicates that the call does not modify (resp.
- * depends on) any static variable.
- *
- * The `effects` and `depends` flag must be used in tandem. Either both are
- * specified or none is.
- *
- * Each tag (including the type tags) may only occur once in the sequence.
- *
- * Guidelines:
- *
- * + Do not use any parameter, local, method or field names in the
- * [codeTemplate]. These names are all subject to arbitrary renaming by the
- * compiler. Pass the values in via `#` substition, and test with the
- * `--minify` dart2js command-line option.
- *
- * + The substituted expressions are values, not locations.
- *
- * JS('void', '# += "x"', this.field);
- *
- * `this.field` might not be a substituted as a reference to the field. The
- * generated code might accidentally work as intended, but it also might be
- *
- * var t1 = this.field;
- * t1 += "x";
- *
- * or
- *
- * this.get$field() += "x";
- *
- * The remedy in this case is to expand the `+=` operator, leaving all
- * references to the Dart field as Dart code:
- *
- * this.field = JS('String', '# + "x"', this.field);
- *
- * + Never use `#` in function bodies.
- *
- * This is a variation on the previous guideline. Since `#` is replaced with
- * an *expression* and the expression is only valid in the immediate context,
- * `#` should never appear in a function body. Doing so might defer the
- * evaluation of the expression, and its side effects, until the function is
- * called.
- *
- * For example,
- *
- * var value = foo();
- * var f = JS('', 'function(){return #}', value)
- *
- * might result in no immediate call to `foo` and a call to `foo` on every
- * call to the JavaScript function bound to `f`. This is better:
- *
- * var f = JS('',
- * '(function(val) { return function(){return val}; })(#)', value);
- *
- * Since `#` occurs in the immediately evaluated expression, the expression
- * is immediately evaluated and bound to `val` in the immediate call.
- *
- *
- * Type argument.
- *
- * In Dart 2.0, the type argument additionally constrains the returned type.
- * So, with type inference filling in the type argumemnt,
- *
- * String s = JS('', 'JSON.stringify(#)', x);
- *
- * will be the same as the current meaning of
- *
- * var s = JS('String|Null', 'JSON.stringify(#)', x);
- *
- *
- * Additional notes.
- *
- * In the future we may extend [typeDescription] to include other aspects of the
- * behavior, for example, separating the returned types from the instantiated
- * types to allow the compiler to perform more optimizations around the code.
- *
- * This might be an extension of [JS] or a new function similar to [JS] with
- * additional arguments for the new information.
- */
+/// Emits a JavaScript code fragment parametrized by arguments.
+///
+/// Hash characters `#` in the [codeTemplate] are replaced in left-to-right
+/// order with expressions that contain the values of, or evaluate to, the
+/// arguments. The number of hash marks must match the number or arguments.
+/// Although declared with arguments [arg0] through [arg2], the form actually
+/// has no limit on the number of arguments.
+///
+/// The [typeDescription] argument is interpreted as a description of the
+/// behavior of the JavaScript code. Currently it describes the side effects
+/// types that may be returned by the expression, with the additional behavior
+/// that the returned values may be fresh instances of the types. The type
+/// information must be correct as it is trusted by the compiler in
+/// optimizations, and it must be precise as possible since it is used for
+/// native live type analysis to tree-shake large parts of the DOM libraries.
+/// If poorly written, the [typeDescription] will cause unnecessarily bloated
+/// programs. (You can check for this by compiling with `--verbose`; there is
+/// an info message describing the number of native (DOM) types that can be
+/// removed, which usually should be greater than zero.)
+///
+/// The [typeDescription] must be a [String]. Two forms of it are supported:
+///
+/// 1) a union of types separated by vertical bar `|` symbols, e.g.
+/// `"num|String"` describes the union of numbers and Strings. There is no
+/// type in Dart that is this precise. The Dart alternative would be
+/// `Object` or `dynamic`, but these types imply that the JS-code might also
+/// be creating instances of all the DOM types.
+///
+/// If `null` is possible, it must be specified explicitly, e.g.
+/// `"String|Null"`. [typeDescription] has several extensions to help
+/// describe the behavior more accurately. In addition to the union type
+/// already described:
+///
+/// + `=Object` is a plain JavaScript object. Some DOM methods return
+/// instances that have no corresponding Dart type (e.g. cross-frame
+/// documents), `=Object` can be used to describe these untyped' values.
+///
+/// + `var` or empty string. If the entire [typeDescription] is `var` (or
+/// empty string) then the type is `dynamic` but the code is known to not
+/// create any instances.
+///
+/// Examples:
+///
+/// // Parent window might be an opaque cross-frame window.
+/// var thing = JS('=Object|Window', '#.parent', myWindow);
+///
+/// 2) a sequence of the form `<tag>:<value>;` where `<tag>` is one of
+/// `creates`, `returns`, `effects` or `depends`.
+///
+/// The first two tags are used to specify the created and returned types of
+/// the expression. The value of `creates` and `returns` is a type string as
+/// defined in 1).
+///
+/// The tags `effects` and `depends` encode the side effects of this call.
+/// They can be omitted, in which case the expression is parsed and a safe
+/// conservative side-effect estimation is computed.
+///
+/// The values of `effects` and `depends` may be 'all', 'none' or a
+/// comma-separated list of 'no-index', 'no-instance' and 'no-static'.
+///
+/// The value 'all' indicates that the call affects/depends on every
+/// side-effect. The flag 'none' signals that the call does not affect
+/// (resp. depends on) anything.
+///
+/// The value 'no-index' indicates that the call does *not* do (resp. depends
+/// on) any array index-store. The flag 'no-instance' indicates that the call
+/// does not modify (resp. depends on) any instance variable. Similarly,
+/// the 'no-static' value indicates that the call does not modify (resp.
+/// depends on) any static variable.
+///
+/// The `effects` and `depends` flag must be used in tandem. Either both are
+/// specified or none is.
+///
+/// Each tag (including the type tags) may only occur once in the sequence.
+///
+/// Guidelines:
+///
+/// + Do not use any parameter, local, method or field names in the
+/// [codeTemplate]. These names are all subject to arbitrary renaming by the
+/// compiler. Pass the values in via `#` substition, and test with the
+/// `--minify` dart2js command-line option.
+///
+/// + The substituted expressions are values, not locations.
+///
+/// JS('void', '# += "x"', this.field);
+///
+/// `this.field` might not be a substituted as a reference to the field. The
+/// generated code might accidentally work as intended, but it also might be
+///
+/// var t1 = this.field;
+/// t1 += "x";
+///
+/// or
+///
+/// this.get$field() += "x";
+///
+/// The remedy in this case is to expand the `+=` operator, leaving all
+/// references to the Dart field as Dart code:
+///
+/// this.field = JS('String', '# + "x"', this.field);
+///
+/// + Never use `#` in function bodies.
+///
+/// This is a variation on the previous guideline. Since `#` is replaced
+/// with an *expression* and the expression is only valid in the immediate
+/// context, `#` should never appear in a function body. Doing so might
+/// defer the evaluation of the expression, and its side effects, until the
+/// function is called.
+///
+/// For example,
+///
+/// var value = foo();
+/// var f = JS('', 'function(){return #}', value)
+///
+/// might result in no immediate call to `foo` and a call to `foo` on every
+/// call to the JavaScript function bound to `f`. This is better:
+///
+/// var f = JS('',
+/// '(function(val) { return function(){return val}; })(#)', value);
+///
+/// Since `#` occurs in the immediately evaluated expression, the expression
+/// is immediately evaluated and bound to `val` in the immediate call.
+///
+///
+/// Type argument.
+///
+/// In Dart 2.0, the type argument additionally constrains the returned type.
+/// So, with type inference filling in the type argumemnt,
+///
+/// String s = JS('', 'JSON.stringify(#)', x);
+///
+/// will be the same as the current meaning of
+///
+/// var s = JS('String|Null', 'JSON.stringify(#)', x);
+///
+///
+/// Additional notes.
+///
+/// In the future we may extend [typeDescription] to include other aspects of
+/// the behavior, for example, separating the returned types from the
+/// instantiated types to allow the compiler to perform more optimizations
+/// around the code.
+///
+/// This might be an extension of [JS] or a new function similar to [JS] with
+/// additional arguments for the new information.
// Add additional optional arguments if needed. The method is treated internally
// as a variable argument method.
external T JS<T>(String typeDescription, String codeTemplate,
@@ -176,39 +175,31 @@
arg18,
arg19]);
-/**
- * Converts the Dart closure [function] into a JavaScript closure.
- *
- * Warning: This is no different from [RAW_DART_FUNCTION_REF] which means care
- * must be taken to store the current isolate.
- */
+/// Converts the Dart closure [function] into a JavaScript closure.
+///
+/// Warning: This is no different from [RAW_DART_FUNCTION_REF] which means care
+/// must be taken to store the current isolate.
external DART_CLOSURE_TO_JS(Function function);
-/**
- * Returns a raw reference to the JavaScript function which implements
- * [function].
- *
- * Warning: this is dangerous, you should probably use
- * [DART_CLOSURE_TO_JS] instead. The returned object is not a valid
- * Dart closure, does not store the isolate context or arity.
- *
- * A valid example of where this can be used is as the second argument
- * to V8's Error.captureStackTrace. See
- * https://code.google.com/p/v8/wiki/JavaScriptStackTraceApi.
- */
+/// Returns a raw reference to the JavaScript function which implements
+/// [function].
+///
+/// Warning: this is dangerous, you should probably use
+/// [DART_CLOSURE_TO_JS] instead. The returned object is not a valid
+/// Dart closure, does not store the isolate context or arity.
+///
+/// A valid example of where this can be used is as the second argument
+/// to V8's Error.captureStackTrace. See
+/// https://code.google.com/p/v8/wiki/JavaScriptStackTraceApi.
external RAW_DART_FUNCTION_REF(Function function);
-/**
- * Sets the current static state to [staticState].
- */
+/// Sets the current static state to [staticState].
external void JS_SET_STATIC_STATE(staticState);
-/**
- * Returns the interceptor for class [type]. The interceptor is the type's
- * constructor's `prototype` property. [type] will typically be the class, not
- * an interface, e.g. `JS_INTERCEPTOR_CONSTANT(JSInt)`, not
- * `JS_INTERCEPTOR_CONSTANT(int)`.
- */
+/// Returns the interceptor for class [type]. The interceptor is the type's
+/// constructor's `prototype` property. [type] will typically be the class, not
+/// an interface, e.g. `JS_INTERCEPTOR_CONSTANT(JSInt)`, not
+/// `JS_INTERCEPTOR_CONSTANT(int)`.
external JS_INTERCEPTOR_CONSTANT(Type type);
/// Returns the interceptor for [object].
@@ -216,9 +207,7 @@
/// Calls are replaced with the [HInterceptor] SSA instruction.
external getInterceptor(object);
-/**
- * Returns the object corresponding to Namer.staticStateHolder.
- */
+/// Returns the object corresponding to Namer.staticStateHolder.
external JS_GET_STATIC_STATE();
/// Returns the JS name for [name] from the Namer.
@@ -242,42 +231,36 @@
/// when the program has been analyzed.
external bool JS_GET_FLAG(String name);
-/**
- * Pretend [code] is executed. Generates no executable code. This is used to
- * model effects at some other point in external code. For example, the
- * following models an assignment to foo with an unknown value.
- *
- * var foo;
- *
- * main() {
- * JS_EFFECT((_){ foo = _; })
- * }
- *
- * TODO(sra): Replace this hack with something to mark the volatile or
- * externally initialized elements.
- */
+/// Pretend [code] is executed. Generates no executable code. This is used to
+/// model effects at some other point in external code. For example, the
+/// following models an assignment to foo with an unknown value.
+///
+/// var foo;
+///
+/// main() {
+/// JS_EFFECT((_){ foo = _; })
+/// }
+///
+/// TODO(sra): Replace this hack with something to mark the volatile or
+/// externally initialized elements.
void JS_EFFECT(Function code) {
code(null);
}
-/**
- * Use this class for creating constants that hold JavaScript code.
- * For example:
- *
- * const constant = JS_CONST('typeof window != "undefined");
- *
- * This code will generate:
- * $.JS_CONST_1 = typeof window != "undefined";
- */
+/// Use this class for creating constants that hold JavaScript code.
+/// For example:
+///
+/// const constant = JS_CONST('typeof window != "undefined");
+///
+/// This code will generate:
+/// $.JS_CONST_1 = typeof window != "undefined";
class JS_CONST {
final String code;
const JS_CONST(this.code);
}
-/**
- * JavaScript string concatenation. Inputs must be Strings. Corresponds to the
- * HStringConcat SSA instruction and may be constant-folded.
- */
+/// JavaScript string concatenation. Inputs must be Strings. Corresponds to the
+/// HStringConcat SSA instruction and may be constant-folded.
String JS_STRING_CONCAT(String a, String b) {
// This body is unused, only here for type analysis.
return JS('String', '# + #', a, b);
diff --git a/sdk/lib/_internal/js_runtime/lib/interceptors.dart b/sdk/lib/_internal/js_runtime/lib/interceptors.dart
index 287ec00..3344d39 100644
--- a/sdk/lib/_internal/js_runtime/lib/interceptors.dart
+++ b/sdk/lib/_internal/js_runtime/lib/interceptors.dart
@@ -123,10 +123,8 @@
dispatchRecordExtension(record) => JS('', '#.e', record);
dispatchRecordIndexability(record) => JS('bool|Null', '#.x', record);
-/**
- * Returns the interceptor for a native class instance. Used by
- * [getInterceptor].
- */
+/// Returns the interceptor for a native class instance. Used by
+/// [getInterceptor].
getNativeInterceptor(object) {
var record = getDispatchProperty(object);
@@ -220,20 +218,18 @@
JS('', '#.set(#, #)', constructorToInterceptor, constructor, interceptor);
}
-/**
- * Data structure used to map a [Type] to the [Interceptor] and constructors for
- * that type. It is JavaScript array of 3N entries of adjacent slots containing
- * a [Type], followed by an [Interceptor] class for the type, followed by a
- * JavaScript object map for the constructors.
- *
- * The value of this variable is set by the compiler and contains only types
- * that are user extensions of native classes where the type occurs as a
- * constant in the program.
- *
- * The compiler, in CustomElementsAnalysis, assumes that [typeToInterceptorMap]
- * is accessed only by code that also calls [findIndexForWebComponentType]. If
- * this assumption is invalidated, the compiler will have to be updated.
- */
+/// Data structure used to map a [Type] to the [Interceptor] and constructors
+/// for that type. It is JavaScript array of 3N entries of adjacent slots
+/// containing a [Type], followed by an [Interceptor] class for the type,
+/// followed by a JavaScript object map for the constructors.
+///
+/// The value of this variable is set by the compiler and contains only types
+/// that are user extensions of native classes where the type occurs as a
+/// constant in the program.
+///
+/// The compiler, in CustomElementsAnalysis, assumes that [typeToInterceptorMap]
+/// is accessed only by code that also calls [findIndexForWebComponentType]. If
+/// this assumption is invalidated, the compiler will have to be updated.
get typeToInterceptorMap {
return JS_EMBEDDED_GLOBAL('', TYPE_TO_INTERCEPTOR_MAP);
}
@@ -256,12 +252,10 @@
return map[index + 1];
}
-/**
- * Returns a JavaScript function that runs the constructor on its argument, or
- * `null` if there is no such constructor.
- *
- * The returned function takes one argument, the web component object.
- */
+/// Returns a JavaScript function that runs the constructor on its argument, or
+/// `null` if there is no such constructor.
+///
+/// The returned function takes one argument, the web component object.
findConstructorForNativeSubclassType(Type type, String name) {
var index = findIndexForNativeSubclassType(type);
if (index == null) return null;
@@ -277,54 +271,52 @@
return JS('', '#.prototype', constructor);
}
-/**
- * The base interceptor class.
- *
- * The code `r.foo(a)` is compiled to `getInterceptor(r).foo$1(r, a)`. The
- * value returned by [getInterceptor] holds the methods separately from the
- * state of the instance. The compiler converts the methods on an interceptor
- * to take the Dart `this` argument as an explicit `receiver` argument. The
- * JavaScript `this` parameter is bound to the interceptor.
- *
- * In order to have uniform call sites, if a method is defined on an
- * interceptor, methods of that name on plain unintercepted classes also use the
- * interceptor calling convention. The plain classes are _self-interceptors_,
- * and for them, `getInterceptor(r)` returns `r`. Methods on plain
- * unintercepted classes have a redundant `receiver` argument and, to enable
- * some optimizations, must ignore `receiver` in favour of `this`.
- *
- * In the case of mixins, a method may be placed on both an intercepted class
- * and an unintercepted class. In this case, the method must use the `receiver`
- * parameter.
- *
- *
- * There are various optimizations of the general call pattern.
- *
- * When the interceptor can be statically determined, it can be used directly:
- *
- * CONSTANT_INTERCEPTOR.foo$1(r, a)
- *
- * If there are only a few classes, [getInterceptor] can be specialized with a
- * more efficient dispatch:
- *
- * getInterceptor$specialized(r).foo$1(r, a)
- *
- * If it can be determined that the receiver is an unintercepted class, it can
- * be called directly:
- *
- * r.foo$1(r, a)
- *
- * If, further, it is known that the call site cannot call a foo that is
- * mixed-in to a native class, then it is known that the explicit receiver is
- * ignored, and space-saving dummy value can be passed instead:
- *
- * r.foo$1(0, a)
- *
- * This class defines implementations of *all* methods on [Object] so no
- * interceptor inherits an implementation from [Object]. This enables the
- * implementations on Object to ignore the explicit receiver argument, which
- * allows dummy receiver optimization.
- */
+/// The base interceptor class.
+///
+/// The code `r.foo(a)` is compiled to `getInterceptor(r).foo$1(r, a)`. The
+/// value returned by [getInterceptor] holds the methods separately from the
+/// state of the instance. The compiler converts the methods on an interceptor
+/// to take the Dart `this` argument as an explicit `receiver` argument. The
+/// JavaScript `this` parameter is bound to the interceptor.
+///
+/// In order to have uniform call sites, if a method is defined on an
+/// interceptor, methods of that name on plain unintercepted classes also use
+/// the interceptor calling convention. The plain classes are
+/// _self-interceptors_, and for them, `getInterceptor(r)` returns `r`. Methods
+/// on plain unintercepted classes have a redundant `receiver` argument and, to
+/// enable some optimizations, must ignore `receiver` in favour of `this`.
+///
+/// In the case of mixins, a method may be placed on both an intercepted class
+/// and an unintercepted class. In this case, the method must use the
+/// `receiver` parameter.
+///
+///
+/// There are various optimizations of the general call pattern.
+///
+/// When the interceptor can be statically determined, it can be used directly:
+///
+/// CONSTANT_INTERCEPTOR.foo$1(r, a)
+///
+/// If there are only a few classes, [getInterceptor] can be specialized with a
+/// more efficient dispatch:
+///
+/// getInterceptor$specialized(r).foo$1(r, a)
+///
+/// If it can be determined that the receiver is an unintercepted class, it can
+/// be called directly:
+///
+/// r.foo$1(r, a)
+///
+/// If, further, it is known that the call site cannot call a foo that is
+/// mixed-in to a native class, then it is known that the explicit receiver is
+/// ignored, and space-saving dummy value can be passed instead:
+///
+/// r.foo$1(0, a)
+///
+/// This class defines implementations of *all* methods on [Object] so no
+/// interceptor inherits an implementation from [Object]. This enables the
+/// implementations on Object to ignore the explicit receiver argument, which
+/// allows dummy receiver optimization.
abstract class Interceptor {
const Interceptor();
@@ -356,9 +348,7 @@
Type get runtimeType => getRuntimeType(this);
}
-/**
- * The interceptor class for [bool].
- */
+/// The interceptor class for [bool].
class JSBool extends Interceptor implements bool {
const JSBool();
@@ -378,13 +368,11 @@
Type get runtimeType => bool;
}
-/**
- * The interceptor class for [Null].
- *
- * This class defines implementations for *all* methods on [Object] since
- * the methods on Object assume the receiver is non-null. This means that
- * JSNull will always be in the interceptor set for methods defined on Object.
- */
+/// The interceptor class for [Null].
+///
+/// This class defines implementations for *all* methods on [Object] since
+/// the methods on Object assume the receiver is non-null. This means that
+/// JSNull will always be in the interceptor set for methods defined on Object.
class JSNull extends Interceptor implements Null {
const JSNull();
@@ -403,37 +391,29 @@
dynamic noSuchMethod(Invocation invocation) => super.noSuchMethod(invocation);
}
-/**
- * The supertype for JSString and JSArray. Used by the backend as to
- * have a type mask that contains the objects that we can use the
- * native JS [] operator and length on.
- */
+/// The supertype for JSString and JSArray. Used by the backend as to
+/// have a type mask that contains the objects that we can use the
+/// native JS [] operator and length on.
abstract class JSIndexable<E> {
int get length;
E operator [](int index);
}
-/**
- * The supertype for JSMutableArray and
- * JavaScriptIndexingBehavior. Used by the backend to have a type mask
- * that contains the objects we can use the JS []= operator on.
- */
+/// The supertype for JSMutableArray and
+/// JavaScriptIndexingBehavior. Used by the backend to have a type mask
+/// that contains the objects we can use the JS []= operator on.
abstract class JSMutableIndexable<E> extends JSIndexable<E> {
operator []=(int index, E value);
}
-/**
- * The interface implemented by JavaScript objects. These are methods in
- * addition to the regular Dart Object methods like [Object.hashCode].
- *
- * This is the type that should be exported by a JavaScript interop library.
- */
+/// The interface implemented by JavaScript objects. These are methods in
+/// addition to the regular Dart Object methods like [Object.hashCode].
+///
+/// This is the type that should be exported by a JavaScript interop library.
abstract class JSObject {}
-/**
- * Interceptor base class for JavaScript objects not recognized as some more
- * specific native type.
- */
+/// Interceptor base class for JavaScript objects not recognized as some more
+/// specific native type.
class JavaScriptObject extends Interceptor implements JSObject {
const JavaScriptObject();
@@ -442,36 +422,28 @@
Type get runtimeType => JSObject;
- /**
- * Returns the result of the JavaScript objects `toString` method.
- */
+ /// Returns the result of the JavaScript objects `toString` method.
String toString() => JS('String', 'String(#)', this);
}
-/**
- * Interceptor for plain JavaScript objects created as JavaScript object
- * literals or `new Object()`.
- */
+/// Interceptor for plain JavaScript objects created as JavaScript object
+/// literals or `new Object()`.
class PlainJavaScriptObject extends JavaScriptObject {
const PlainJavaScriptObject();
}
-/**
- * Interceptor for unclassified JavaScript objects, typically objects with a
- * non-trivial prototype chain.
- *
- * This class also serves as a fallback for unknown JavaScript exceptions.
- */
+/// Interceptor for unclassified JavaScript objects, typically objects with a
+/// non-trivial prototype chain.
+///
+/// This class also serves as a fallback for unknown JavaScript exceptions.
class UnknownJavaScriptObject extends JavaScriptObject {
const UnknownJavaScriptObject();
}
-/**
- * Interceptor for JavaScript function objects and Dart functions that have
- * been converted to JavaScript functions.
- * These interceptor methods are not always used as the JavaScript function
- * object has also been mangled to support Dart function calling conventions.
- */
+/// Interceptor for JavaScript function objects and Dart functions that have
+/// been converted to JavaScript functions.
+/// These interceptor methods are not always used as the JavaScript function
+/// object has also been mangled to support Dart function calling conventions.
class JavaScriptFunction extends JavaScriptObject implements Function {
const JavaScriptFunction();
diff --git a/sdk/lib/_internal/js_runtime/lib/js_array.dart b/sdk/lib/_internal/js_runtime/lib/js_array.dart
index 9d0a48e..c6956d9 100644
--- a/sdk/lib/_internal/js_runtime/lib/js_array.dart
+++ b/sdk/lib/_internal/js_runtime/lib/js_array.dart
@@ -10,12 +10,10 @@
const _ListConstructorSentinel = const _Growable();
-/**
- * The interceptor class for [List]. The compiler recognizes this
- * class as an interceptor, and changes references to [:this:] to
- * actually use the receiver of the method, which is generated as an extra
- * argument added to each member.
- */
+/// The interceptor class for [List]. The compiler recognizes this
+/// class as an interceptor, and changes references to [:this:] to
+/// actually use the receiver of the method, which is generated as an extra
+/// argument added to each member.
class JSArray<E> extends Interceptor implements List<E>, JSIndexable {
const JSArray();
@@ -28,11 +26,9 @@
return new JSArray<E>.fixed(length);
}
- /**
- * Returns a fresh JavaScript Array, marked as fixed-length.
- *
- * [length] must be a non-negative integer.
- */
+ /// Returns a fresh JavaScript Array, marked as fixed-length.
+ ///
+ /// [length] must be a non-negative integer.
factory JSArray.fixed(int length) {
// Explicit type test is necessary to guard against JavaScript conversions
// in unchecked mode, and against `new Array(null)` which creates a single
@@ -49,16 +45,12 @@
return new JSArray<E>.markFixed(JS('', 'new Array(#)', length));
}
- /**
- * Returns a fresh growable JavaScript Array of zero length length.
- */
+ /// Returns a fresh growable JavaScript Array of zero length length.
factory JSArray.emptyGrowable() => new JSArray<E>.markGrowable(JS('', '[]'));
- /**
- * Returns a fresh growable JavaScript Array with initial length.
- *
- * [validatedLength] must be a non-negative integer.
- */
+ /// Returns a fresh growable JavaScript Array with initial length.
+ ///
+ /// [validatedLength] must be a non-negative integer.
factory JSArray.growable(int length) {
// Explicit type test is necessary to guard against JavaScript conversions
// in unchecked mode.
@@ -68,20 +60,18 @@
return new JSArray<E>.markGrowable(JS('', 'new Array(#)', length));
}
- /**
- * Constructor for adding type parameters to an existing JavaScript Array.
- * The compiler specially recognizes this constructor.
- *
- * var a = new JSArray<int>.typed(JS('JSExtendableArray', '[]'));
- * a is List<int> --> true
- * a is List<String> --> false
- *
- * Usually either the [JSArray.markFixed] or [JSArray.markGrowable]
- * constructors is used instead.
- *
- * The input must be a JavaScript Array. The JS form is just a re-assertion
- * to help type analysis when the input type is sloppy.
- */
+ /// Constructor for adding type parameters to an existing JavaScript Array.
+ /// The compiler specially recognizes this constructor.
+ ///
+ /// var a = new JSArray<int>.typed(JS('JSExtendableArray', '[]'));
+ /// a is List<int> --> true
+ /// a is List<String> --> false
+ ///
+ /// Usually either the [JSArray.markFixed] or [JSArray.markGrowable]
+ /// constructors is used instead.
+ ///
+ /// The input must be a JavaScript Array. The JS form is just a re-assertion
+ /// to help type analysis when the input type is sloppy.
factory JSArray.typed(allocation) => JS('JSArray', '#', allocation);
factory JSArray.markFixed(allocation) =>
@@ -181,9 +171,7 @@
return false;
}
- /**
- * Removes elements matching [test] from [this] List.
- */
+ /// Removes elements matching [test] from [this] List.
void removeWhere(bool test(E element)) {
checkGrowable('removeWhere');
_removeWhere(test, true);
@@ -677,17 +665,15 @@
}
}
-/**
- * Dummy subclasses that allow the backend to track more precise
- * information about arrays through their type. The CPA type inference
- * relies on the fact that these classes do not override [] nor []=.
- *
- * These classes are really a fiction, and can have no methods, since
- * getInterceptor always returns JSArray. We should consider pushing the
- * 'isGrowable' and 'isMutable' checks into the getInterceptor implementation so
- * these classes can have specialized implementations. Doing so will challenge
- * many assumptions in the JS backend.
- */
+/// Dummy subclasses that allow the backend to track more precise
+/// information about arrays through their type. The CPA type inference
+/// relies on the fact that these classes do not override [] nor []=.
+///
+/// These classes are really a fiction, and can have no methods, since
+/// getInterceptor always returns JSArray. We should consider pushing the
+/// 'isGrowable' and 'isMutable' checks into the getInterceptor implementation
+/// so these classes can have specialized implementations. Doing so will
+/// challenge many assumptions in the JS backend.
class JSMutableArray<E> extends JSArray<E> implements JSMutableIndexable {}
class JSFixedArray<E> extends JSMutableArray<E> {}
diff --git a/sdk/lib/_internal/js_runtime/lib/js_helper.dart b/sdk/lib/_internal/js_runtime/lib/js_helper.dart
index 61e7182..9457101 100644
--- a/sdk/lib/_internal/js_runtime/lib/js_helper.dart
+++ b/sdk/lib/_internal/js_runtime/lib/js_helper.dart
@@ -646,7 +646,7 @@
return result;
}
- /** [: r"$".codeUnitAt(0) :] */
+ /// [: r"$".codeUnitAt(0) :]
static const int DOLLAR_CHAR_VALUE = 36;
/// Creates a string containing the complete type for the class [className]
@@ -1099,39 +1099,37 @@
0));
}
- /**
- * Implements [Function.apply] for the lazy and startup emitters.
- *
- * There are two types of closures that can reach this function:
- *
- * 1. tear-offs (including tear-offs of static functions).
- * 2. anonymous closures.
- *
- * They are treated differently (although there are lots of similarities).
- * Both have in common that they have
- * a [JsGetName.CALL_CATCH_ALL] and
- * a [JsGetName.REQUIRED_PARAMETER_PROPERTY] property.
- *
- * If the closure supports optional parameters, then they also feature
- * a [JsGetName.DEFAULT_VALUES_PROPERTY] property.
- *
- * The catch-all property is a method that takes all arguments (including
- * all optional positional or named arguments). If the function accepts
- * optional arguments, then the default-values property stores (potentially
- * wrapped in a function) the default values for the optional arguments. If
- * the function accepts optional positional arguments, then the value is a
- * JavaScript array with the default values. Otherwise, when the function
- * accepts optional named arguments, it is a JavaScript object.
- *
- * The default-values property may either contain the value directly, or
- * it can be a function that returns the default-values when invoked.
- *
- * If the function is an anonymous closure, then the catch-all property
- * only contains a string pointing to the property that should be used
- * instead. For example, if the catch-all property contains the string
- * "call$4", then the object's "call$4" property should be used as if it was
- * the value of the catch-all property.
- */
+ /// Implements [Function.apply] for the lazy and startup emitters.
+ ///
+ /// There are two types of closures that can reach this function:
+ ///
+ /// 1. tear-offs (including tear-offs of static functions).
+ /// 2. anonymous closures.
+ ///
+ /// They are treated differently (although there are lots of similarities).
+ /// Both have in common that they have
+ /// a [JsGetName.CALL_CATCH_ALL] and
+ /// a [JsGetName.REQUIRED_PARAMETER_PROPERTY] property.
+ ///
+ /// If the closure supports optional parameters, then they also feature
+ /// a [JsGetName.DEFAULT_VALUES_PROPERTY] property.
+ ///
+ /// The catch-all property is a method that takes all arguments (including
+ /// all optional positional or named arguments). If the function accepts
+ /// optional arguments, then the default-values property stores (potentially
+ /// wrapped in a function) the default values for the optional arguments. If
+ /// the function accepts optional positional arguments, then the value is a
+ /// JavaScript array with the default values. Otherwise, when the function
+ /// accepts optional named arguments, it is a JavaScript object.
+ ///
+ /// The default-values property may either contain the value directly, or
+ /// it can be a function that returns the default-values when invoked.
+ ///
+ /// If the function is an anonymous closure, then the catch-all property
+ /// only contains a string pointing to the property that should be used
+ /// instead. For example, if the catch-all property contains the string
+ /// "call$4", then the object's "call$4" property should be used as if it was
+ /// the value of the catch-all property.
static applyFunction(Function function, List positionalArguments,
Map<String, dynamic> namedArguments) {
// Fast shortcut for the common case.
@@ -1328,32 +1326,27 @@
}
}
-/**
- * Called by generated code to throw an illegal-argument exception,
- * for example, if a non-integer index is given to an optimized
- * indexed access.
- */
+/// Called by generated code to throw an illegal-argument exception,
+/// for example, if a non-integer index is given to an optimized
+/// indexed access.
@NoInline()
iae(argument) {
throw argumentErrorValue(argument);
}
-/**
- * Called by generated code to throw an index-out-of-range exception, for
- * example, if a bounds check fails in an optimized indexed access. This may
- * also be called when the index is not an integer, in which case it throws an
- * illegal-argument exception instead, like [iae], or when the receiver is null.
- */
+/// Called by generated code to throw an index-out-of-range exception, for
+/// example, if a bounds check fails in an optimized indexed access. This may
+/// also be called when the index is not an integer, in which case it throws an
+/// illegal-argument exception instead, like [iae], or when the receiver is
+/// null.
@NoInline()
ioore(receiver, index) {
if (receiver == null) receiver.length; // Force a NoSuchMethodError.
throw diagnoseIndexError(receiver, index);
}
-/**
- * Diagnoses an indexing error. Returns the ArgumentError or RangeError that
- * describes the problem.
- */
+/// Diagnoses an indexing error. Returns the ArgumentError or RangeError that
+/// describes the problem.
@NoInline()
Error diagnoseIndexError(indexable, index) {
if (index is! int) return new ArgumentError.value(index, 'index');
@@ -1367,10 +1360,8 @@
return new RangeError.value(index, 'index');
}
-/**
- * Diagnoses a range error. Returns the ArgumentError or RangeError that
- * describes the problem.
- */
+/// Diagnoses a range error. Returns the ArgumentError or RangeError that
+/// describes the problem.
@NoInline()
Error diagnoseRangeError(start, end, length) {
if (start is! int) {
@@ -1426,12 +1417,10 @@
return value;
}
-/**
- * Wrap the given Dart object and record a stack trace.
- *
- * The code in [unwrapException] deals with getting the original Dart
- * object out of the wrapper again.
- */
+/// Wrap the given Dart object and record a stack trace.
+///
+/// The code in [unwrapException] deals with getting the original Dart
+/// object out of the wrapper again.
@NoInline()
wrapException(ex) {
if (ex == null) ex = new NullThrownError();
@@ -1463,12 +1452,10 @@
return JS('', r'this.dartException').toString();
}
-/**
- * This wraps the exception and does the throw. It is possible to call this in
- * a JS expression context, where the throw statement is not allowed. Helpers
- * are never inlined, so we don't risk inlining the throw statement into an
- * expression context.
- */
+/// This wraps the exception and does the throw. It is possible to call this in
+/// a JS expression context, where the throw statement is not allowed. Helpers
+/// are never inlined, so we don't risk inlining the throw statement into an
+/// expression context.
throwExpression(ex) {
JS('void', 'throw #', wrapException(ex));
}
@@ -1510,9 +1497,7 @@
throw new ConcurrentModificationError(collection);
}
-/**
- * Helper class for building patterns recognizing native type errors.
- */
+/// Helper class for building patterns recognizing native type errors.
class TypeErrorDecoder {
// Field names are private to help tree-shaking.
@@ -1891,14 +1876,12 @@
ExceptionAndStackTrace(this.dartException, this.stackTrace);
}
-/**
- * Called from catch blocks in generated code to extract the Dart
- * exception from the thrown value. The thrown value may have been
- * created by [wrapException] or it may be a 'native' JS exception.
- *
- * Some native exceptions are mapped to new Dart instances, others are
- * returned unmodified.
- */
+/// Called from catch blocks in generated code to extract the Dart
+/// exception from the thrown value. The thrown value may have been
+/// created by [wrapException] or it may be a 'native' JS exception.
+///
+/// Some native exceptions are mapped to new Dart instances, others are
+/// returned unmodified.
unwrapException(ex) {
/// If error implements Error, save [ex] in [error.$thrownJsError].
/// Otherwise, do nothing. Later, the stack trace can then be extracted from
@@ -2048,10 +2031,8 @@
ex);
}
-/**
- * Called by generated code to fetch the stack trace from an
- * exception. Should never return null.
- */
+/// Called by generated code to fetch the stack trace from an
+/// exception. Should never return null.
StackTrace getTraceFromException(exception) {
if (exception is ExceptionAndStackTrace) {
return exception.stackTrace;
@@ -2088,10 +2069,8 @@
}
}
-/**
- * Called by generated code to build a map literal. [keyValuePairs] is
- * a list of key, value, key, value, ..., etc.
- */
+/// Called by generated code to build a map literal. [keyValuePairs] is
+/// a list of key, value, key, value, ..., etc.
fillLiteralMap(keyValuePairs, Map result) {
// TODO(johnniwinther): Use JSArray to optimize this code instead of calling
// [getLength] and [getIndex].
@@ -2122,10 +2101,8 @@
throw new Exception('Unsupported number of arguments for wrapped closure');
}
-/**
- * Called by generated code to convert a Dart closure to a JS
- * closure when the Dart closure is passed to the DOM.
- */
+/// Called by generated code to convert a Dart closure to a JS
+/// closure when the Dart closure is passed to the DOM.
convertDartClosureToJS(closure, int arity) {
if (closure == null) return null;
var function = JS('var', r'#.$identity', closure);
@@ -2162,40 +2139,36 @@
static const OPTIONAL_PARAMETER_INDEX = 4;
static const DEFAULT_ARGUMENTS_INDEX = 5;
- /**
- * Global counter to prevent reusing function code objects.
- *
- * V8 will share the underlying function code objects when the same string is
- * passed to "new Function". Shared function code objects can lead to
- * sub-optimal performance due to polymorphism, and can be prevented by
- * ensuring the strings are different, for example, by generating a local
- * variable with a name dependent on [functionCounter].
- */
+ /// Global counter to prevent reusing function code objects.
+ ///
+ /// V8 will share the underlying function code objects when the same string is
+ /// passed to "new Function". Shared function code objects can lead to
+ /// sub-optimal performance due to polymorphism, and can be prevented by
+ /// ensuring the strings are different, for example, by generating a local
+ /// variable with a name dependent on [functionCounter].
static int functionCounter = 0;
Closure();
- /**
- * Creates a new closure class for use by implicit getters associated with a
- * method.
- *
- * In other words, creates a tear-off closure.
- *
- * Called from [closureFromTearOff] as well as from reflection when tearing
- * of a method via `getField`.
- *
- * This method assumes that [functions] was created by the JavaScript function
- * `addStubs` in `reflection_data_parser.dart`. That is, a list of JavaScript
- * function objects with properties `$stubName` and `$callName`.
- *
- * Further assumes that [reflectionInfo] is the end of the array created by
- * [dart2js.js_emitter.ContainerBuilder.addMemberMethod] starting with
- * required parameter count or, in case of the new emitter, the runtime
- * representation of the function's type.
- *
- * Caution: this function may be called when building constants.
- * TODO(ahe): Don't call this function when building constants.
- */
+ /// Creates a new closure class for use by implicit getters associated with a
+ /// method.
+ ///
+ /// In other words, creates a tear-off closure.
+ ///
+ /// Called from [closureFromTearOff] as well as from reflection when tearing
+ /// of a method via `getField`.
+ ///
+ /// This method assumes that [functions] was created by the JavaScript
+ /// function `addStubs` in `reflection_data_parser.dart`. That is, a list of
+ /// JavaScript function objects with properties `$stubName` and `$callName`.
+ ///
+ /// Further assumes that [reflectionInfo] is the end of the array created by
+ /// [dart2js.js_emitter.ContainerBuilder.addMemberMethod] starting with
+ /// required parameter count or, in case of the new emitter, the runtime
+ /// representation of the function's type.
+ ///
+ /// Caution: this function may be called when building constants.
+ /// TODO(ahe): Don't call this function when building constants.
static fromTearOff(
receiver,
List functions,
@@ -2757,101 +2730,91 @@
return JS('var', r'#[#]', jsObject, property);
}
-/**
- * Called at the end of unaborted switch cases to get the singleton
- * FallThroughError exception that will be thrown.
- */
+/// Called at the end of unaborted switch cases to get the singleton
+/// FallThroughError exception that will be thrown.
getFallThroughError() => new FallThroughErrorImplementation();
-/**
- * A metadata annotation describing the types instantiated by a native element.
- *
- * The annotation is valid on a native method and a field of a native class.
- *
- * By default, a field of a native class is seen as an instantiation point for
- * all native classes that are a subtype of the field's type, and a native
- * method is seen as an instantiation point fo all native classes that are a
- * subtype of the method's return type, or the argument types of the declared
- * type of the method's callback parameter.
- *
- * An @[Creates] annotation overrides the default set of instantiated types. If
- * one or more @[Creates] annotations are present, the type of the native
- * element is ignored, and the union of @[Creates] annotations is used instead.
- * The names in the strings are resolved and the program will fail to compile
- * with dart2js if they do not name types.
- *
- * The argument to [Creates] is a string. The string is parsed as the names of
- * one or more types, separated by vertical bars `|`. There are some special
- * names:
- *
- * * `=Object`. This means 'exactly Object', which is a plain JavaScript object
- * with properties and none of the subtypes of Object.
- *
- * Example: we may know that a method always returns a specific implementation:
- *
- * @Creates('_NodeList')
- * List<Node> getElementsByTagName(String tag) native;
- *
- * Useful trick: A method can be marked as not instantiating any native classes
- * with the annotation `@Creates('Null')`. This is useful for fields on native
- * classes that are used only in Dart code.
- *
- * @Creates('Null')
- * var _cachedFoo;
- */
+/// A metadata annotation describing the types instantiated by a native element.
+///
+/// The annotation is valid on a native method and a field of a native class.
+///
+/// By default, a field of a native class is seen as an instantiation point for
+/// all native classes that are a subtype of the field's type, and a native
+/// method is seen as an instantiation point fo all native classes that are a
+/// subtype of the method's return type, or the argument types of the declared
+/// type of the method's callback parameter.
+///
+/// An @[Creates] annotation overrides the default set of instantiated types.
+/// If one or more @[Creates] annotations are present, the type of the native
+/// element is ignored, and the union of @[Creates] annotations is used instead.
+/// The names in the strings are resolved and the program will fail to compile
+/// with dart2js if they do not name types.
+///
+/// The argument to [Creates] is a string. The string is parsed as the names of
+/// one or more types, separated by vertical bars `|`. There are some special
+/// names:
+///
+/// * `=Object`. This means 'exactly Object', which is a plain JavaScript object
+/// with properties and none of the subtypes of Object.
+///
+/// Example: we may know that a method always returns a specific implementation:
+///
+/// @Creates('_NodeList')
+/// List<Node> getElementsByTagName(String tag) native;
+///
+/// Useful trick: A method can be marked as not instantiating any native classes
+/// with the annotation `@Creates('Null')`. This is useful for fields on native
+/// classes that are used only in Dart code.
+///
+/// @Creates('Null')
+/// var _cachedFoo;
class Creates {
final String types;
const Creates(this.types);
}
-/**
- * A metadata annotation describing the types returned or yielded by a native
- * element.
- *
- * The annotation is valid on a native method and a field of a native class.
- *
- * By default, a native method or field is seen as returning or yielding all
- * subtypes if the method return type or field type. This annotation allows a
- * more precise set of types to be specified.
- *
- * See [Creates] for the syntax of the argument.
- *
- * Example: IndexedDB keys are numbers, strings and JavaScript Arrays of keys.
- *
- * @Returns('String|num|JSExtendableArray')
- * dynamic key;
- *
- * // Equivalent:
- * @Returns('String') @Returns('num') @Returns('JSExtendableArray')
- * dynamic key;
- */
+/// A metadata annotation describing the types returned or yielded by a native
+/// element.
+///
+/// The annotation is valid on a native method and a field of a native class.
+///
+/// By default, a native method or field is seen as returning or yielding all
+/// subtypes if the method return type or field type. This annotation allows a
+/// more precise set of types to be specified.
+///
+/// See [Creates] for the syntax of the argument.
+///
+/// Example: IndexedDB keys are numbers, strings and JavaScript Arrays of keys.
+///
+/// @Returns('String|num|JSExtendableArray')
+/// dynamic key;
+///
+/// // Equivalent:
+/// @Returns('String') @Returns('num') @Returns('JSExtendableArray')
+/// dynamic key;
class Returns {
final String types;
const Returns(this.types);
}
-/**
- * A metadata annotation placed on native methods and fields of native classes
- * to specify the JavaScript name.
- *
- * This example declares a Dart field + getter + setter called `$dom_title` that
- * corresponds to the JavaScript property `title`.
- *
- * class Document native "*Foo" {
- * @JSName('title')
- * String $dom_title;
- * }
- */
+/// A metadata annotation placed on native methods and fields of native classes
+/// to specify the JavaScript name.
+///
+/// This example declares a Dart field + getter + setter called `$dom_title`
+/// that corresponds to the JavaScript property `title`.
+///
+/// class Document native "*Foo" {
+/// @JSName('title')
+/// String $dom_title;
+/// }
class JSName {
final String name;
const JSName(this.name);
}
-/**
- * The following methods are called by the runtime to implement
- * checked mode and casts. We specialize each primitive type (eg int, bool), and
- * use the compiler's convention to do is-checks on regular objects.
- */
+/// The following methods are called by the runtime to implement checked mode
+/// and casts. We specialize each primitive type (eg int, bool), and use the
+/// compiler's convention to do is-checks on regular objects.
boolConversionCheck(value) {
if (value is bool) return value;
// One of the following checks will always fail.
@@ -2926,32 +2889,26 @@
throw new CastErrorImplementation(value, unminifyOrTag(name));
}
-/**
- * For types that are not supertypes of native (eg DOM) types,
- * we emit a simple property check to check that an object implements
- * that type.
- */
+/// For types that are not supertypes of native (eg DOM) types,
+/// we emit a simple property check to check that an object implements
+/// that type.
propertyTypeCheck(value, property) {
if (value == null) return value;
if (JS('bool', '!!#[#]', value, property)) return value;
propertyTypeError(value, property);
}
-/**
- * For types that are not supertypes of native (eg DOM) types,
- * we emit a simple property check to check that an object implements
- * that type.
- */
+/// For types that are not supertypes of native (eg DOM) types,
+/// we emit a simple property check to check that an object implements
+/// that type.
propertyTypeCast(value, property) {
if (value == null || JS('bool', '!!#[#]', value, property)) return value;
propertyTypeCastError(value, property);
}
-/**
- * For types that are supertypes of native (eg DOM) types, we use the
- * interceptor for the class because we cannot add a JS property to the
- * prototype at load time.
- */
+/// For types that are supertypes of native (eg DOM) types, we use the
+/// interceptor for the class because we cannot add a JS property to the
+/// prototype at load time.
interceptedTypeCheck(value, property) {
if (value == null) return value;
if ((JS('bool', 'typeof # === "object"', value) ||
@@ -2962,11 +2919,9 @@
propertyTypeError(value, property);
}
-/**
- * For types that are supertypes of native (eg DOM) types, we use the
- * interceptor for the class because we cannot add a JS property to the
- * prototype at load time.
- */
+/// For types that are supertypes of native (eg DOM) types, we use the
+/// interceptor for the class because we cannot add a JS property to the
+/// prototype at load time.
interceptedTypeCast(value, property) {
if (value == null ||
((JS('bool', 'typeof # === "object"', value) ||
@@ -2977,10 +2932,8 @@
propertyTypeCastError(value, property);
}
-/**
- * Specialization of the type check for num and String and their
- * supertype since [value] can be a JS primitive.
- */
+/// Specialization of the type check for num and String and their
+/// supertype since [value] can be a JS primitive.
numberOrStringSuperTypeCheck(value, property) {
if (value == null) return value;
if (value is String) return value;
@@ -3011,10 +2964,8 @@
propertyTypeCastError(value, property);
}
-/**
- * Specialization of the type check for String and its supertype
- * since [value] can be a JS primitive.
- */
+/// Specialization of the type check for String and its supertype
+/// since [value] can be a JS primitive.
stringSuperTypeCheck(value, property) {
if (value == null) return value;
if (value is String) return value;
@@ -3040,10 +2991,8 @@
propertyTypeCastError(value, property);
}
-/**
- * Specialization of the type check for List and its supertypes,
- * since [value] can be a JS array.
- */
+/// Specialization of the type check for List and its supertypes,
+/// since [value] can be a JS array.
listTypeCheck(value) {
if (value == null) return value;
if (value is List) return value;
@@ -3158,17 +3107,15 @@
}
}
-/**
- * Special interface recognized by the compiler and implemented by DOM
- * objects that support integer indexing. This interface is not
- * visible to anyone, and is only injected into special libraries.
- */
+/// Special interface recognized by the compiler and implemented by DOM
+/// objects that support integer indexing. This interface is not
+/// visible to anyone, and is only injected into special libraries.
abstract class JavaScriptIndexingBehavior<E> extends JSMutableIndexable<E> {}
// TODO(lrn): These exceptions should be implemented in core.
// When they are, remove the 'Implementation' here.
-/** Thrown by type assertions that fail. */
+/// Thrown by type assertions that fail.
class TypeErrorImplementation extends Error implements TypeError {
final String message;
@@ -3182,7 +3129,7 @@
String toString() => message;
}
-/** Thrown by the 'as' operator if the cast isn't valid. */
+/// Thrown by the 'as' operator if the cast isn't valid.
class CastErrorImplementation extends Error implements CastError {
// TODO(lrn): Rename to CastError (and move implementation into core).
final String message;
@@ -3211,12 +3158,11 @@
String toString() => 'Switch case fall-through.';
}
-/**
- * Helper function for implementing asserts. The compiler treats this specially.
- *
- * Returns the negation of the condition. That is: `true` if the assert should
- * fail.
- */
+/// Helper function for implementing asserts. The compiler treats this
+/// specially.
+///
+/// Returns the negation of the condition. That is: `true` if the assert should
+/// fail.
bool assertTest(condition) {
// Do bool success check first, it is common and faster than 'is Function'.
if (true == condition) return false;
@@ -3224,44 +3170,34 @@
throw new TypeErrorImplementation(condition, 'bool');
}
-/**
- * Helper function for implementing asserts with messages.
- * The compiler treats this specially.
- */
+/// Helper function for implementing asserts with messages.
+/// The compiler treats this specially.
void assertThrow(Object message) {
throw new _AssertionError(message);
}
-/**
- * Helper function for implementing asserts without messages.
- * The compiler treats this specially.
- */
+/// Helper function for implementing asserts without messages.
+/// The compiler treats this specially.
@NoInline()
void assertHelper(condition) {
if (assertTest(condition)) throw new AssertionError();
}
-/**
- * Called by generated code when a method that must be statically
- * resolved cannot be found.
- */
+/// Called by generated code when a method that must be statically
+/// resolved cannot be found.
void throwNoSuchMethod(obj, name, arguments, expectedArgumentNames) {
Symbol memberName = new _symbol_dev.Symbol.unvalidated(name);
throw new NoSuchMethodError(obj, memberName, arguments,
new Map<Symbol, dynamic>(), expectedArgumentNames);
}
-/**
- * Called by generated code when a static field's initializer references the
- * field that is currently being initialized.
- */
+/// Called by generated code when a static field's initializer references the
+/// field that is currently being initialized.
void throwCyclicInit(String staticName) {
throw new CyclicInitializationError(staticName);
}
-/**
- * Error thrown when a runtime error occurs.
- */
+/// Error thrown when a runtime error occurs.
class RuntimeError extends Error {
final message;
RuntimeError(this.message);
@@ -3288,11 +3224,9 @@
String toString() => 'Unsupported operation: $_message';
}
-/**
- * Creates a random number with 64 bits of randomness.
- *
- * This will be truncated to the 53 bits available in a double.
- */
+/// Creates a random number with 64 bits of randomness.
+///
+/// This will be truncated to the 53 bits available in a double.
int random64() {
// TODO(lrn): Use a secure random source.
int int32a = JS('int', '(Math.random() * 0x100000000) >>> 0');
@@ -3304,14 +3238,12 @@
return JS('String', 'JSON.stringify(#)', string);
}
-/**
- * Returns a property name for placing data on JavaScript objects shared between
- * DOM isolates. This happens when multiple programs are loaded in the same
- * JavaScript context (i.e. page). The name is based on [name] but with an
- * additional part that is unique for each isolate.
- *
- * The form of the name is '___dart_$name_$id'.
- */
+/// Returns a property name for placing data on JavaScript objects shared
+/// between DOM isolates. This happens when multiple programs are loaded in the
+/// same JavaScript context (i.e. page). The name is based on [name] but with
+/// an additional part that is unique for each isolate.
+///
+/// The form of the name is '___dart_$name_$id'.
String getIsolateAffinityTag(String name) {
var isolateTagGetter = JS_EMBEDDED_GLOBAL('', GET_ISOLATE_TAG);
return JS('String', '#(#)', isolateTagGetter, name);
diff --git a/sdk/lib/_internal/js_runtime/lib/js_names.dart b/sdk/lib/_internal/js_runtime/lib/js_names.dart
index d3eaa07..572d354 100644
--- a/sdk/lib/_internal/js_runtime/lib/js_names.dart
+++ b/sdk/lib/_internal/js_runtime/lib/js_names.dart
@@ -139,17 +139,15 @@
return new JSArray.markFixed(result);
}
-/**
- * Returns the (global) unmangled version of [name].
- *
- * Normally, you should use [mangledGlobalNames] directly, but this method
- * doesn't tell the compiler to preserve names. So this method only returns a
- * non-null value if some other component has made the compiler preserve names.
- *
- * This is used, for example, to return unmangled names from TypeImpl.toString
- * *if* names are being preserved for other reasons (use of dart:mirrors, for
- * example).
- */
+/// Returns the (global) unmangled version of [name].
+///
+/// Normally, you should use [mangledGlobalNames] directly, but this method
+/// doesn't tell the compiler to preserve names. So this method only returns a
+/// non-null value if some other component has made the compiler preserve names.
+///
+/// This is used, for example, to return unmangled names from TypeImpl.toString
+/// *if* names are being preserved for other reasons (use of dart:mirrors, for
+/// example).
String unmangleGlobalNameIfPreservedAnyways(String name) {
var names = JS_EMBEDDED_GLOBAL('=Object', MANGLED_GLOBAL_NAMES);
return JsCache.fetch(names, name);
diff --git a/sdk/lib/_internal/js_runtime/lib/js_number.dart b/sdk/lib/_internal/js_runtime/lib/js_number.dart
index fed5dd8..1c030f3 100644
--- a/sdk/lib/_internal/js_runtime/lib/js_number.dart
+++ b/sdk/lib/_internal/js_runtime/lib/js_number.dart
@@ -4,15 +4,13 @@
part of _interceptors;
-/**
- * The super interceptor class for [JSInt] and [JSDouble]. The compiler
- * recognizes this class as an interceptor, and changes references to
- * [:this:] to actually use the receiver of the method, which is
- * generated as an extra argument added to each member.
- *
- * Note that none of the methods here delegate to a method defined on JSInt or
- * JSDouble. This is exploited in [tryComputeConstantInterceptor].
- */
+/// The super interceptor class for [JSInt] and [JSDouble]. The compiler
+/// recognizes this class as an interceptor, and changes references to
+/// [:this:] to actually use the receiver of the method, which is
+/// generated as an extra argument added to each member.
+///
+/// Note that none of the methods here delegate to a method defined on JSInt or
+/// JSDouble. This is exploited in [tryComputeConstantInterceptor].
class JSNumber extends Interceptor implements double {
const JSNumber();
@@ -444,14 +442,12 @@
Type get runtimeType => num;
}
-/**
- * The interceptor class for [int]s.
- *
- * This class implements double (indirectly through JSNumber) since in
- * JavaScript all numbers are doubles, so while we want to treat `2.0` as an
- * integer for some operations, its interceptor should answer `true` to `is
- * double`.
- */
+/// The interceptor class for [int]s.
+///
+/// This class implements double (indirectly through JSNumber) since in
+/// JavaScript all numbers are doubles, so while we want to treat `2.0` as an
+/// integer for some operations, its interceptor should answer `true` to `is
+/// double`.
class JSInt extends JSNumber implements int {
const JSInt();
diff --git a/sdk/lib/_internal/js_runtime/lib/js_primitives.dart b/sdk/lib/_internal/js_runtime/lib/js_primitives.dart
index 40c451c..97577a0 100644
--- a/sdk/lib/_internal/js_runtime/lib/js_primitives.dart
+++ b/sdk/lib/_internal/js_runtime/lib/js_primitives.dart
@@ -8,15 +8,13 @@
import 'dart:_foreign_helper' show JS;
-/**
- * This is the low-level method that is used to implement [print]. It is
- * possible to override this function from JavaScript by defining a function in
- * JavaScript called "dartPrint".
- *
- * Notice that it is also possible to intercept calls to [print] from within a
- * Dart program using zones. This means that there is no guarantee that a call
- * to print ends in this method.
- */
+/// This is the low-level method that is used to implement [print]. It is
+/// possible to override this function from JavaScript by defining a function in
+/// JavaScript called "dartPrint".
+///
+/// Notice that it is also possible to intercept calls to [print] from within a
+/// Dart program using zones. This means that there is no guarantee that a call
+/// to print ends in this method.
void printString(String string) {
if (JS('bool', r'typeof dartPrint == "function"')) {
// Support overriding print from JavaScript.
diff --git a/sdk/lib/_internal/js_runtime/lib/js_rti.dart b/sdk/lib/_internal/js_runtime/lib/js_rti.dart
index b5e84fa..9a6ef99 100644
--- a/sdk/lib/_internal/js_runtime/lib/js_rti.dart
+++ b/sdk/lib/_internal/js_runtime/lib/js_rti.dart
@@ -2,43 +2,41 @@
// 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.
-/**
- * This part contains helpers for supporting runtime type information.
- *
- * The helper use a mixture of Dart and JavaScript objects. To indicate which is
- * used where we adopt the scheme of using explicit type annotation for Dart
- * objects and 'var' or omitted return type for JavaScript objects.
- *
- * Since bool, int, and String values are represented by the same JavaScript
- * primitives, type annotations are used for these types in all cases.
- *
- * Several methods use a common JavaScript encoding of runtime type information.
- * This encoding is referred to as the type representation which is one of
- * these:
- * 1) a JavaScript constructor for a class C: the represented type is the raw
- * type C.
- * 2) a JavaScript array: the first entry is of type 1 and contains the
- * subtyping flags and the substitution of the type and the rest of the
- * array are the type arguments.
- * 3) `null`: the dynamic type.
- * 4) a JavaScript object representing the function type. For instance, it has
- * the form {ret: rti, args: [rti], opt: [rti], named: {name: rti}} for a
- * function with a return type, regular, optional and named arguments.
- * Generic function types have a 'bounds' property.
- *
- * To check subtype relations between generic classes we use a JavaScript
- * expression that describes the necessary substitution for type arguments.
- * Such a substitution expression can be:
- * 1) `null`, if no substituted check is necessary, because the
- * type variables are the same or there are no type variables in the class
- * that is checked for.
- * 2) A list expression describing the type arguments to be used in the
- * subtype check, if the type arguments to be used in the check do not
- * depend on the type arguments of the object.
- * 3) A function mapping the type variables of the object to be checked to
- * a list expression. The function may also return null, which is equivalent
- * to an array containing only null values.
- */
+/// This part contains helpers for supporting runtime type information.
+///
+/// The helper use a mixture of Dart and JavaScript objects. To indicate which
+/// is used where we adopt the scheme of using explicit type annotation for Dart
+/// objects and 'var' or omitted return type for JavaScript objects.
+///
+/// Since bool, int, and String values are represented by the same JavaScript
+/// primitives, type annotations are used for these types in all cases.
+///
+/// Several methods use a common JavaScript encoding of runtime type
+/// information. This encoding is referred to as the type representation which
+/// is one of these:
+/// 1) a JavaScript constructor for a class C: the represented type is the raw
+/// type C.
+/// 2) a JavaScript array: the first entry is of type 1 and contains the
+/// subtyping flags and the substitution of the type and the rest of the
+/// array are the type arguments.
+/// 3) `null`: the dynamic type.
+/// 4) a JavaScript object representing the function type. For instance, it has
+/// the form {ret: rti, args: [rti], opt: [rti], named: {name: rti}} for a
+/// function with a return type, regular, optional and named arguments.
+/// Generic function types have a 'bounds' property.
+///
+/// To check subtype relations between generic classes we use a JavaScript
+/// expression that describes the necessary substitution for type arguments.
+/// Such a substitution expression can be:
+/// 1) `null`, if no substituted check is necessary, because the
+/// type variables are the same or there are no type variables in the class
+/// that is checked for.
+/// 2) A list expression describing the type arguments to be used in the
+/// subtype check, if the type arguments to be used in the check do not
+/// depend on the type arguments of the object.
+/// 3) A function mapping the type variables of the object to be checked to a
+/// list expression. The function may also return null, which is equivalent
+/// to an array containing only null values.
part of _js_helper;
@@ -67,12 +65,10 @@
}
}
-/**
- * Represents a type variable.
- *
- * This class holds the information needed when reflecting on generic classes
- * and their members.
- */
+/// Represents a type variable.
+///
+/// This class holds the information needed when reflecting on generic classes
+/// and their members.
class TypeVariable {
final Type owner;
final String name;
@@ -157,10 +153,8 @@
return rti == null ? null : getIndex(rti, index);
}
-/**
- * Retrieves the class name from type information stored on the constructor
- * of [object].
- */
+/// Retrieves the class name from type information stored on the constructor
+/// of [object].
String getClassName(var object) {
return rawRtiToJsConstructorName(getRawRuntimeType(getInterceptor(object)));
}
@@ -327,11 +321,9 @@
return '${typeParameters}(${argumentsText}) => ${returnTypeText}';
}
-/**
- * Creates a comma-separated string of human-readable representations of the
- * type representations in the JavaScript array [types] starting at index
- * [startIndex].
- */
+/// Creates a comma-separated string of human-readable representations of the
+/// type representations in the JavaScript array [types] starting at index
+/// [startIndex].
String joinArguments(var types, int startIndex) {
return _joinArguments(types, startIndex, null);
}
@@ -354,11 +346,9 @@
return '<$buffer>';
}
-/**
- * Returns a human-readable representation of the type of [object].
- *
- * In minified mode does *not* use unminified identifiers (even when present).
- */
+/// Returns a human-readable representation of the type of [object].
+///
+/// In minified mode does *not* use unminified identifiers (even when present).
String getRuntimeTypeString(var object) {
if (object is Closure) {
// This excludes classes that implement Function via a `call` method, but
@@ -403,12 +393,10 @@
return new TypeImpl(getRti(object));
}
-/**
- * Applies the [substitution] on the [arguments].
- *
- * See the comment in the beginning of this file for a description of the
- * possible values for [substitution].
- */
+/// Applies the [substitution] on the [arguments].
+///
+/// See the comment in the beginning of this file for a description of the
+/// possible values for [substitution].
substitute(var substitution, var arguments) {
if (substitution == null) return arguments;
assert(isJsFunction(substitution));
@@ -429,18 +417,16 @@
return arguments;
}
-/**
- * Perform a type check with arguments on the Dart object [object].
- *
- * Parameters:
- * - [isField]: the name of the flag/function to check if the object
- * is of the correct class.
- * - [checks]: the (JavaScript) list of type representations for the
- * arguments to check against.
- * - [asField]: the name of the function that transforms the type
- * arguments of [objects] to an instance of the class that we check
- * against.
- */
+/// Perform a type check with arguments on the Dart object [object].
+///
+/// Parameters:
+/// - [isField]: the name of the flag/function to check if the object
+/// is of the correct class.
+/// - [checks]: the (JavaScript) list of type representations for the
+/// arguments to check against.
+/// - [asField]: the name of the function that transforms the type
+/// arguments of [objects] to an instance of the class that we check
+/// against.
bool checkSubtype(Object object, String isField, List checks, String asField) {
if (object == null) return false;
var arguments = getRuntimeTypeInfo(object);
@@ -507,17 +493,15 @@
return areSubtypes(substitute(substitution, arguments), sEnv, checks, tEnv);
}
-/**
- * Checks whether the types of [s] are all subtypes of the types of [t].
- *
- * [s] and [t] are either `null` or JavaScript arrays of type representations,
- * A `null` argument is interpreted as the arguments of a raw type, that is a
- * list of `dynamic`. If [s] and [t] are JavaScript arrays they must be of the
- * same length.
- *
- * See the comment in the beginning of this file for a description of type
- * representations.
- */
+/// Checks whether the types of [s] are all subtypes of the types of [t].
+///
+/// [s] and [t] are either `null` or JavaScript arrays of type representations,
+/// A `null` argument is interpreted as the arguments of a raw type, that is a
+/// list of `dynamic`. If [s] and [t] are JavaScript arrays they must be of the
+/// same length.
+///
+/// See the comment in the beginning of this file for a description of type
+/// representations.
bool areSubtypes(var s, var sEnv, var t, var tEnv) {
// `null` means a raw type.
@@ -545,10 +529,8 @@
return true;
}
-/**
- * Computes the signature by applying the type arguments of [context] as an
- * instance of [contextName] to the signature function [signature].
- */
+/// Computes the signature by applying the type arguments of [context] as an
+/// instance of [contextName] to the signature function [signature].
computeSignature(var signature, var context, var contextName) {
var interceptor = getInterceptor(context);
var typeArguments =
@@ -619,13 +601,11 @@
: null;
}
-/**
- * Tests whether the Dart object [o] is a subtype of the runtime type
- * representation [t].
- *
- * See the comment in the beginning of this file for a description of type
- * representations.
- */
+/// Tests whether the Dart object [o] is a subtype of the runtime type
+/// representation [t].
+///
+/// See the comment in the beginning of this file for a description of type
+/// representations.
bool checkSubtypeOfRuntimeType(o, t) {
if (o == null) return isSupertypeOfNull(t);
if (isTopType(t)) return true;
@@ -678,24 +658,20 @@
return object;
}
-/**
- * Extracts the type arguments from a type representation. The result is a
- * JavaScript array or `null`.
- */
+/// Extracts the type arguments from a type representation. The result is a
+/// JavaScript array or `null`.
getArguments(var type) {
return isJsArray(type) ? JS('var', r'#.slice(1)', type) : null;
}
-/**
- * Checks whether the type represented by the type representation [s] is a
- * subtype of the type represented by the type representation [t].
- *
- * See the comment in the beginning of this file for a description of type
- * representations.
- *
- * The arguments [s] and [t] must be types, usually represented by the
- * constructor of the class, or an array (for generic class types).
- */
+/// Checks whether the type represented by the type representation [s] is a
+/// subtype of the type represented by the type representation [t].
+///
+/// See the comment in the beginning of this file for a description of type
+/// representations.
+///
+/// The arguments [s] and [t] must be types, usually represented by the
+/// constructor of the class, or an array (for generic class types).
bool isSubtype(var s, var t) {
return _isSubtype(s, null, t, null);
}
@@ -1075,16 +1051,12 @@
return array;
}
-/**
- * Calls the JavaScript [function] with the [arguments] with the global scope
- * as the `this` context.
- */
+/// Calls the JavaScript [function] with the [arguments] with the global scope
+/// as the `this` context.
invoke(var function, var arguments) => invokeOn(function, null, arguments);
-/**
- * Calls the JavaScript [function] with the [arguments] with [receiver] as the
- * `this` context.
- */
+/// Calls the JavaScript [function] with the [arguments] with [receiver] as the
+/// `this` context.
Object invokeOn(function, receiver, arguments) {
assert(isJsFunction(function));
assert(arguments == null || isJsArray(arguments));
@@ -1132,18 +1104,14 @@
/// Returns `true` if [o] is a JavaScript object.
bool isJsObject(var o) => JS('bool', r"typeof # == 'object'", o);
-/**
- * Returns `true` if the JavaScript values [s] and [t] are identical. We use
- * this helper instead of [identical] because `identical` needs to merge
- * `null` and `undefined` (which we can avoid).
- */
+/// Returns `true` if the JavaScript values [s] and [t] are identical. We use
+/// this helper instead of [identical] because `identical` needs to merge
+/// `null` and `undefined` (which we can avoid).
bool isIdentical(var s, var t) => JS('bool', '# === #', s, t);
-/**
- * Returns `true` if the JavaScript values [s] and [t] are not identical. We use
- * this helper instead of [identical] because `identical` needs to merge
- * `null` and `undefined` (which we can avoid).
- */
+/// Returns `true` if the JavaScript values [s] and [t] are not identical. We
+/// use this helper instead of [identical] because `identical` needs to merge
+/// `null` and `undefined` (which we can avoid).
bool isNotIdentical(var s, var t) => JS('bool', '# !== #', s, t);
/// 'Top' bounds are uninteresting: null/undefined and Object.
diff --git a/sdk/lib/_internal/js_runtime/lib/js_string.dart b/sdk/lib/_internal/js_runtime/lib/js_string.dart
index 91e9734..baa47b6 100644
--- a/sdk/lib/_internal/js_runtime/lib/js_string.dart
+++ b/sdk/lib/_internal/js_runtime/lib/js_string.dart
@@ -4,12 +4,10 @@
part of _interceptors;
-/**
- * The interceptor class for [String]. The compiler recognizes this
- * class as an interceptor, and changes references to [:this:] to
- * actually use the receiver of the method, which is generated as an extra
- * argument added to each member.
- */
+/// The interceptor class for [String]. The compiler recognizes this
+/// class as an interceptor, and changes references to [:this:] to
+/// actually use the receiver of the method, which is generated as an extra
+/// argument added to each member.
class JSString extends Interceptor implements String, JSIndexable {
const JSString();
@@ -443,12 +441,10 @@
// Note: if you change this, also change the function [S].
String toString() => this;
- /**
- * This is the [Jenkins hash function][1] but using masking to keep
- * values in SMI range.
- *
- * [1]: http://en.wikipedia.org/wiki/Jenkins_hash_function
- */
+ /// This is the [Jenkins hash function][1] but using masking to keep
+ /// values in SMI range.
+ ///
+ /// [1]: http://en.wikipedia.org/wiki/Jenkins_hash_function
int get hashCode {
// TODO(ahe): This method shouldn't have to use JS. Update when our
// optimizations are smarter.
diff --git a/sdk/lib/_internal/js_runtime/lib/math_patch.dart b/sdk/lib/_internal/js_runtime/lib/math_patch.dart
index 68bae9a..a3d3fc9 100644
--- a/sdk/lib/_internal/js_runtime/lib/math_patch.dart
+++ b/sdk/lib/_internal/js_runtime/lib/math_patch.dart
@@ -84,15 +84,11 @@
return JS('int', '(Math.random() * #) >>> 0', max);
}
- /**
- * Generates a positive random floating point value uniformly distributed on
- * the range from 0.0, inclusive, to 1.0, exclusive.
- */
+ /// Generates a positive random floating point value uniformly distributed on
+ /// the range from 0.0, inclusive, to 1.0, exclusive.
double nextDouble() => JS('double', 'Math.random()');
- /**
- * Generates a random boolean value.
- */
+ /// Generates a random boolean value.
bool nextBool() => JS('bool', 'Math.random() < 0.5');
}
diff --git a/sdk/lib/_internal/js_runtime/lib/native_helper.dart b/sdk/lib/_internal/js_runtime/lib/native_helper.dart
index fa11112..59a3719 100644
--- a/sdk/lib/_internal/js_runtime/lib/native_helper.dart
+++ b/sdk/lib/_internal/js_runtime/lib/native_helper.dart
@@ -38,27 +38,21 @@
return JS('var', 'Object.getPrototypeOf(#)[#]', object, name);
}
-/**
- * Returns a String tag identifying the type of the native object, or `null`.
- * The tag is not the name of the type, but usually the name of the JavaScript
- * constructor function. Initialized by [initHooks].
- */
+/// Returns a String tag identifying the type of the native object, or `null`.
+/// The tag is not the name of the type, but usually the name of the JavaScript
+/// constructor function. Initialized by [initHooks].
Function getTagFunction;
-/**
- * If a lookup via [getTagFunction] on an object [object] that has [tag] fails,
- * this function is called to provide an alternate tag. This allows us to fail
- * gracefully if we can make a good guess, for example, when browsers add novel
- * kinds of HTMLElement that we have never heard of. Initialized by
- * [initHooks].
- */
+/// If a lookup via [getTagFunction] on an object [object] that has [tag] fails,
+/// this function is called to provide an alternate tag. This allows us to fail
+/// gracefully if we can make a good guess, for example, when browsers add novel
+/// kinds of HTMLElement that we have never heard of. Initialized by
+/// [initHooks].
Function alternateTagFunction;
-/**
- * Returns the prototype for the JavaScript constructor named by an input tag.
- * Returns `null` if there is no such constructor, or if pre-patching of the
- * constructor is to be avoided. Initialized by [initHooks].
- */
+/// Returns the prototype for the JavaScript constructor named by an input tag.
+/// Returns `null` if there is no such constructor, or if pre-patching of the
+/// constructor is to be avoided. Initialized by [initHooks].
Function prototypeForTagFunction;
String toStringForNativeObject(var obj) {
@@ -73,9 +67,7 @@
int hashCodeForNativeObject(object) => Primitives.objectHashCode(object);
-/**
- * Sets a JavaScript property on an object.
- */
+/// Sets a JavaScript property on an object.
void defineProperty(var obj, String property, var value) {
JS(
'void',
@@ -97,20 +89,16 @@
'depends:none;effects:none;', JsBuiltin.dartObjectConstructor));
}
-/**
- * A JavaScript object mapping tags to the constructors of interceptors.
- * This is a JavaScript object with no prototype.
- *
- * Example: 'HTMLImageElement' maps to the ImageElement class constructor.
- */
+/// A JavaScript object mapping tags to the constructors of interceptors.
+/// This is a JavaScript object with no prototype.
+///
+/// Example: 'HTMLImageElement' maps to the ImageElement class constructor.
get interceptorsByTag => JS_EMBEDDED_GLOBAL('=Object', INTERCEPTORS_BY_TAG);
-/**
- * A JavaScript object mapping tags to `true` or `false`.
- *
- * Example: 'HTMLImageElement' maps to `true` since, as there are no subclasses
- * of ImageElement, it is a leaf class in the native class hierarchy.
- */
+/// A JavaScript object mapping tags to `true` or `false`.
+///
+/// Example: 'HTMLImageElement' maps to `true` since, as there are no subclasses
+/// of ImageElement, it is a leaf class in the native class hierarchy.
get leafTags => JS_EMBEDDED_GLOBAL('=Object', LEAF_TAGS);
String findDispatchTagForInterceptorClass(interceptorClassConstructor) {
@@ -118,17 +106,13 @@
'', r'#.#', interceptorClassConstructor, NATIVE_SUPERCLASS_TAG_NAME);
}
-/**
- * Cache of dispatch records for instances. This is a JavaScript object used as
- * a map. Keys are instance tags, e.g. "!SomeThing". The cache permits the
- * sharing of one dispatch record between multiple instances.
- */
+/// Cache of dispatch records for instances. This is a JavaScript object used
+/// as a map. Keys are instance tags, e.g. "!SomeThing". The cache permits the
+/// sharing of one dispatch record between multiple instances.
var dispatchRecordsForInstanceTags;
-/**
- * Cache of interceptors indexed by uncacheable tags, e.g. "~SomeThing".
- * This is a JavaScript object used as a map.
- */
+/// Cache of interceptors indexed by uncacheable tags, e.g. "~SomeThing".
+/// This is a JavaScript object used as a map.
var interceptorsForUncacheableTags;
lookupInterceptor(String tag) {
@@ -155,12 +139,10 @@
/// A 'discriminator' function is to be used. TBD.
const DISCRIMINATED_MARK = '*';
-/**
- * Returns the interceptor for a native object, or returns `null` if not found.
- *
- * A dispatch record is cached according to the specification of the dispatch
- * tag for [obj].
- */
+/// Returns the interceptor for a native object, or returns `null` if not found.
+///
+/// A dispatch record is cached according to the specification of the dispatch
+/// tag for [obj].
@NoInline()
lookupAndCacheInterceptor(obj) {
assert(!isDartObject(obj));
@@ -270,10 +252,8 @@
}
}
-/**
- * [proto] should have no shadowing prototypes that are not also assigned a
- * dispatch rescord.
- */
+/// [proto] should have no shadowing prototypes that are not also assigned a
+/// dispatch rescord.
setNativeSubclassDispatchRecord(proto, interceptor) {
setDispatchProperty(proto, makeLeafDispatchRecord(interceptor));
}
@@ -338,41 +318,39 @@
}
}
-/**
- * Initializes [getTagFunction] and [alternateTagFunction].
- *
- * These functions are 'hook functions', collectively 'hooks'. They initialized
- * by applying a series of hooks transformers. Built-in hooks transformers deal
- * with various known browser behaviours.
- *
- * Each hook tranformer takes a 'hooks' input which is a JavaScript object
- * containing the hook functions, and returns the same or a new object with
- * replacements. The replacements can wrap the originals to provide alternate
- * or modified behaviour.
- *
- * { getTag: function(obj) {...},
- * getUnknownTag: function(obj, tag) {...},
- * prototypeForTag: function(tag) {...},
- * discriminator: function(tag) {...},
- * }
- *
- * * getTag(obj) returns the dispatch tag, or `null`.
- * * getUnknownTag(obj, tag) returns a tag when [getTag] fails.
- * * prototypeForTag(tag) returns the prototype of the constructor for tag,
- * or `null` if not available or prepatching is undesirable.
- * * discriminator(tag) returns a function TBD.
- *
- * The web site can adapt a dart2js application by loading code ahead of the
- * dart2js application that defines hook transformers to be after the built in
- * ones. Code defining a transformer HT should use the following pattern to
- * ensure multiple transformers can be composed:
- *
- * (dartNativeDispatchHooksTransformer =
- * window.dartNativeDispatchHooksTransformer || []).push(HT);
- *
- *
- * TODO: Implement and describe dispatch tags and their caching methods.
- */
+/// Initializes [getTagFunction] and [alternateTagFunction].
+///
+/// These functions are 'hook functions', collectively 'hooks'. They
+/// initialized by applying a series of hooks transformers. Built-in hooks
+/// transformers deal with various known browser behaviours.
+///
+/// Each hook tranformer takes a 'hooks' input which is a JavaScript object
+/// containing the hook functions, and returns the same or a new object with
+/// replacements. The replacements can wrap the originals to provide alternate
+/// or modified behaviour.
+///
+/// { getTag: function(obj) {...},
+/// getUnknownTag: function(obj, tag) {...},
+/// prototypeForTag: function(tag) {...},
+/// discriminator: function(tag) {...},
+/// }
+///
+/// * getTag(obj) returns the dispatch tag, or `null`.
+/// * getUnknownTag(obj, tag) returns a tag when [getTag] fails.
+/// * prototypeForTag(tag) returns the prototype of the constructor for tag,
+/// or `null` if not available or prepatching is undesirable.
+/// * discriminator(tag) returns a function TBD.
+///
+/// The web site can adapt a dart2js application by loading code ahead of the
+/// dart2js application that defines hook transformers to be after the built in
+/// ones. Code defining a transformer HT should use the following pattern to
+/// ensure multiple transformers can be composed:
+///
+/// (dartNativeDispatchHooksTransformer =
+/// window.dartNativeDispatchHooksTransformer || []).push(HT);
+///
+///
+/// TODO: Implement and describe dispatch tags and their caching methods.
void initHooks() {
// The initial simple hooks:
var hooks = JS('', '#()', _baseHooks);
@@ -478,14 +456,12 @@
discriminator: discriminator };
}''');
-/**
- * Returns the name of the constructor function for browsers where
- * `object.constructor.name` is not reliable.
- *
- * This function is split out of [_fallbackConstructorHooksTransformerGenerator]
- * as it is called from both the dispatch hooks and via
- * [constructorNameFallback] from objectToString.
- */
+/// Returns the name of the constructor function for browsers where
+/// `object.constructor.name` is not reliable.
+///
+/// This function is split out of
+/// [_fallbackConstructorHooksTransformerGenerator] as it is called from both
+/// the dispatch hooks and via [constructorNameFallback] from objectToString.
const _constructorNameFallback = const JS_CONST(r'''
function getTagFallback(o) {
var s = Object.prototype.toString.call(o);
diff --git a/sdk/lib/_internal/js_runtime/lib/native_typed_data.dart b/sdk/lib/_internal/js_runtime/lib/native_typed_data.dart
index 7889c36..9fa9070 100644
--- a/sdk/lib/_internal/js_runtime/lib/native_typed_data.dart
+++ b/sdk/lib/_internal/js_runtime/lib/native_typed_data.dart
@@ -2,10 +2,8 @@
// 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.
-/**
- * Specialized integers and floating point numbers,
- * with SIMD support and efficient lists.
- */
+/// Specialized integers and floating point numbers,
+/// with SIMD support and efficient lists.
library dart.typed_data.implementation;
import 'dart:collection' show ListMixin;
@@ -99,20 +97,16 @@
}
}
-/**
- * A fixed-length list of Float32x4 numbers that is viewable as a
- * [TypedData]. For long lists, this implementation will be considerably more
- * space- and time-efficient than the default [List] implementation.
- */
+/// A fixed-length list of Float32x4 numbers that is viewable as a
+/// [TypedData]. For long lists, this implementation will be considerably more
+/// space- and time-efficient than the default [List] implementation.
class NativeFloat32x4List extends Object
with ListMixin<Float32x4>, FixedLengthListMixin<Float32x4>
implements Float32x4List {
final NativeFloat32List _storage;
- /**
- * Creates a [Float32x4List] of the specified length (in elements),
- * all of whose elements are initially zero.
- */
+ /// Creates a [Float32x4List] of the specified length (in elements),
+ /// all of whose elements are initially zero.
NativeFloat32x4List(int length)
: _storage = new NativeFloat32List(length * 4);
@@ -131,10 +125,8 @@
Type get runtimeType => Float32x4List;
- /**
- * Creates a [Float32x4List] with the same size as the [elements] list
- * and copies over the elements.
- */
+ /// Creates a [Float32x4List] with the same size as the [elements] list
+ /// and copies over the elements.
factory NativeFloat32x4List.fromList(List<Float32x4> list) {
if (list is NativeFloat32x4List) {
return new NativeFloat32x4List._externalStorage(
@@ -178,20 +170,16 @@
}
}
-/**
- * A fixed-length list of Int32x4 numbers that is viewable as a
- * [TypedData]. For long lists, this implementation will be considerably more
- * space- and time-efficient than the default [List] implementation.
- */
+/// A fixed-length list of Int32x4 numbers that is viewable as a
+/// [TypedData]. For long lists, this implementation will be considerably more
+/// space- and time-efficient than the default [List] implementation.
class NativeInt32x4List extends Object
with ListMixin<Int32x4>, FixedLengthListMixin<Int32x4>
implements Int32x4List {
final Int32List _storage;
- /**
- * Creates a [Int32x4List] of the specified length (in elements),
- * all of whose elements are initially zero.
- */
+ /// Creates a [Int32x4List] of the specified length (in elements),
+ /// all of whose elements are initially zero.
NativeInt32x4List(int length) : _storage = new NativeInt32List(length * 4);
NativeInt32x4List._externalStorage(Int32List storage) : _storage = storage;
@@ -209,10 +197,8 @@
Type get runtimeType => Int32x4List;
- /**
- * Creates a [Int32x4List] with the same size as the [elements] list
- * and copies over the elements.
- */
+ /// Creates a [Int32x4List] with the same size as the [elements] list
+ /// and copies over the elements.
factory NativeInt32x4List.fromList(List<Int32x4> list) {
if (list is NativeInt32x4List) {
return new NativeInt32x4List._externalStorage(
@@ -256,20 +242,16 @@
}
}
-/**
- * A fixed-length list of Float64x2 numbers that is viewable as a
- * [TypedData]. For long lists, this implementation will be considerably more
- * space- and time-efficient than the default [List] implementation.
- */
+/// A fixed-length list of Float64x2 numbers that is viewable as a
+/// [TypedData]. For long lists, this implementation will be considerably more
+/// space- and time-efficient than the default [List] implementation.
class NativeFloat64x2List extends Object
with ListMixin<Float64x2>, FixedLengthListMixin<Float64x2>
implements Float64x2List {
final NativeFloat64List _storage;
- /**
- * Creates a [Float64x2List] of the specified length (in elements),
- * all of whose elements are initially zero.
- */
+ /// Creates a [Float64x2List] of the specified length (in elements),
+ /// all of whose elements are initially zero.
NativeFloat64x2List(int length)
: _storage = new NativeFloat64List(length * 2);
@@ -284,10 +266,8 @@
}
}
- /**
- * Creates a [Float64x2List] with the same size as the [elements] list
- * and copies over the elements.
- */
+ /// Creates a [Float64x2List] with the same size as the [elements] list
+ /// and copies over the elements.
factory NativeFloat64x2List.fromList(List<Float64x2> list) {
if (list is NativeFloat64x2List) {
return new NativeFloat64x2List._externalStorage(
@@ -331,30 +311,22 @@
@Native('ArrayBufferView')
class NativeTypedData implements TypedData {
- /**
- * Returns the byte buffer associated with this object.
- */
+ /// Returns the byte buffer associated with this object.
@Creates('NativeByteBuffer')
// May be Null for IE's CanvasPixelArray.
@Returns('NativeByteBuffer|Null')
final ByteBuffer buffer;
- /**
- * Returns the length of this view, in bytes.
- */
+ /// Returns the length of this view, in bytes.
@JSName('byteLength')
final int lengthInBytes;
- /**
- * Returns the offset in bytes into the underlying byte buffer of this view.
- */
+ /// Returns the offset in bytes into the underlying byte buffer of this view.
@JSName('byteOffset')
final int offsetInBytes;
- /**
- * Returns the number of bytes in the representation of each element in this
- * list.
- */
+ /// Returns the number of bytes in the representation of each element in this
+ /// list.
@JSName('BYTES_PER_ELEMENT')
final int elementSizeInBytes;
@@ -413,24 +385,20 @@
@Native('DataView')
class NativeByteData extends NativeTypedData implements ByteData {
- /**
- * Creates a [ByteData] of the specified length (in elements), all of
- * whose elements are initially zero.
- */
+ /// Creates a [ByteData] of the specified length (in elements), all of
+ /// whose elements are initially zero.
factory NativeByteData(int length) => _create1(_checkLength(length));
- /**
- * Creates an [ByteData] _view_ of the specified region in the specified
- * byte buffer. Changes in the [ByteData] will be visible in the byte
- * buffer and vice versa. If the [offsetInBytes] index of the region is not
- * specified, it defaults to zero (the first byte in the byte buffer).
- * If the length is not specified, it defaults to null, which indicates
- * that the view extends to the end of the byte buffer.
- *
- * Throws [RangeError] if [offsetInBytes] or [length] are negative, or
- * if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
- * the length of [buffer].
- */
+ /// Creates an [ByteData] _view_ of the specified region in the specified
+ /// byte buffer. Changes in the [ByteData] will be visible in the byte
+ /// buffer and vice versa. If the [offsetInBytes] index of the region is not
+ /// specified, it defaults to zero (the first byte in the byte buffer).
+ /// If the length is not specified, it defaults to null, which indicates
+ /// that the view extends to the end of the byte buffer.
+ ///
+ /// Throws [RangeError] if [offsetInBytes] or [length] are negative, or
+ /// if [offsetInBytes] + ([length] * elementSizeInBytes) is greater than
+ /// the length of [buffer].
factory NativeByteData.view(
ByteBuffer buffer, int offsetInBytes, int length) {
_checkViewArguments(buffer, offsetInBytes, length);
@@ -443,14 +411,12 @@
int get elementSizeInBytes => 1;
- /**
- * Returns the floating point number represented by the four bytes at
- * the specified [byteOffset] in this object, in IEEE 754
- * single-precision binary floating-point format (binary32).
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 4` is greater than the length of this object.
- */
+ /// Returns the floating point number represented by the four bytes at
+ /// the specified [byteOffset] in this object, in IEEE 754
+ /// single-precision binary floating-point format (binary32).
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 4` is greater than the length of this object.
double getFloat32(int byteOffset, [Endian endian = Endian.big]) =>
_getFloat32(byteOffset, Endian.little == endian);
@@ -458,14 +424,12 @@
@Returns('num')
num _getFloat32(int byteOffset, [bool littleEndian]) native;
- /**
- * Returns the floating point number represented by the eight bytes at
- * the specified [byteOffset] in this object, in IEEE 754
- * double-precision binary floating-point format (binary64).
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 8` is greater than the length of this object.
- */
+ /// Returns the floating point number represented by the eight bytes at
+ /// the specified [byteOffset] in this object, in IEEE 754
+ /// double-precision binary floating-point format (binary64).
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 8` is greater than the length of this object.
double getFloat64(int byteOffset, [Endian endian = Endian.big]) =>
_getFloat64(byteOffset, Endian.little == endian);
@@ -473,16 +437,14 @@
@Returns('num')
num _getFloat64(int byteOffset, [bool littleEndian]) native;
- /**
- * Returns the (possibly negative) integer represented by the two bytes at
- * the specified [byteOffset] in this object, in two's complement binary
- * form.
- * The return value will be between 2<sup>15</sup> and 2<sup>15</sup> - 1,
- * inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 2` is greater than the length of this object.
- */
+ /// Returns the (possibly negative) integer represented by the two bytes at
+ /// the specified [byteOffset] in this object, in two's complement binary
+ /// form.
+ /// The return value will be between 2<sup>15</sup> and 2<sup>15</sup> - 1,
+ /// inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 2` is greater than the length of this object.
int getInt16(int byteOffset, [Endian endian = Endian.big]) =>
_getInt16(byteOffset, Endian.little == endian);
@@ -490,16 +452,14 @@
@Returns('int')
int _getInt16(int byteOffset, [bool littleEndian]) native;
- /**
- * Returns the (possibly negative) integer represented by the four bytes at
- * the specified [byteOffset] in this object, in two's complement binary
- * form.
- * The return value will be between 2<sup>31</sup> and 2<sup>31</sup> - 1,
- * inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 4` is greater than the length of this object.
- */
+ /// Returns the (possibly negative) integer represented by the four bytes at
+ /// the specified [byteOffset] in this object, in two's complement binary
+ /// form.
+ /// The return value will be between 2<sup>31</sup> and 2<sup>31</sup> - 1,
+ /// inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 4` is greater than the length of this object.
int getInt32(int byteOffset, [Endian endian = Endian.big]) =>
_getInt32(byteOffset, Endian.little == endian);
@@ -507,39 +467,33 @@
@Returns('int')
int _getInt32(int byteOffset, [bool littleEndian]) native;
- /**
- * Returns the (possibly negative) integer represented by the eight bytes at
- * the specified [byteOffset] in this object, in two's complement binary
- * form.
- * The return value will be between 2<sup>63</sup> and 2<sup>63</sup> - 1,
- * inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 8` is greater than the length of this object.
- */
+ /// Returns the (possibly negative) integer represented by the eight bytes at
+ /// the specified [byteOffset] in this object, in two's complement binary
+ /// form.
+ /// The return value will be between 2<sup>63</sup> and 2<sup>63</sup> - 1,
+ /// inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 8` is greater than the length of this object.
int getInt64(int byteOffset, [Endian endian = Endian.big]) {
throw new UnsupportedError('Int64 accessor not supported by dart2js.');
}
- /**
- * Returns the (possibly negative) integer represented by the byte at the
- * specified [byteOffset] in this object, in two's complement binary
- * representation. The return value will be between -128 and 127, inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * greater than or equal to the length of this object.
- */
+ /// Returns the (possibly negative) integer represented by the byte at the
+ /// specified [byteOffset] in this object, in two's complement binary
+ /// representation. The return value will be between -128 and 127, inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// greater than or equal to the length of this object.
int getInt8(int byteOffset) native;
- /**
- * Returns the positive integer represented by the two bytes starting
- * at the specified [byteOffset] in this object, in unsigned binary
- * form.
- * The return value will be between 0 and 2<sup>16</sup> - 1, inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 2` is greater than the length of this object.
- */
+ /// Returns the positive integer represented by the two bytes starting
+ /// at the specified [byteOffset] in this object, in unsigned binary
+ /// form.
+ /// The return value will be between 0 and 2<sup>16</sup> - 1, inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 2` is greater than the length of this object.
int getUint16(int byteOffset, [Endian endian = Endian.big]) =>
_getUint16(byteOffset, Endian.little == endian);
@@ -547,15 +501,13 @@
@Returns('JSUInt31')
int _getUint16(int byteOffset, [bool littleEndian]) native;
- /**
- * Returns the positive integer represented by the four bytes starting
- * at the specified [byteOffset] in this object, in unsigned binary
- * form.
- * The return value will be between 0 and 2<sup>32</sup> - 1, inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 4` is greater than the length of this object.
- */
+ /// Returns the positive integer represented by the four bytes starting
+ /// at the specified [byteOffset] in this object, in unsigned binary
+ /// form.
+ /// The return value will be between 0 and 2<sup>32</sup> - 1, inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 4` is greater than the length of this object.
int getUint32(int byteOffset, [Endian endian = Endian.big]) =>
_getUint32(byteOffset, Endian.little == endian);
@@ -563,172 +515,148 @@
@Returns('JSUInt32')
int _getUint32(int byteOffset, [bool littleEndian]) native;
- /**
- * Returns the positive integer represented by the eight bytes starting
- * at the specified [byteOffset] in this object, in unsigned binary
- * form.
- * The return value will be between 0 and 2<sup>64</sup> - 1, inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 8` is greater than the length of this object.
- */
+ /// Returns the positive integer represented by the eight bytes starting
+ /// at the specified [byteOffset] in this object, in unsigned binary
+ /// form.
+ /// The return value will be between 0 and 2<sup>64</sup> - 1, inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 8` is greater than the length of this object.
int getUint64(int byteOffset, [Endian endian = Endian.big]) {
throw new UnsupportedError('Uint64 accessor not supported by dart2js.');
}
- /**
- * Returns the positive integer represented by the byte at the specified
- * [byteOffset] in this object, in unsigned binary form. The
- * return value will be between 0 and 255, inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * greater than or equal to the length of this object.
- */
+ /// Returns the positive integer represented by the byte at the specified
+ /// [byteOffset] in this object, in unsigned binary form. The
+ /// return value will be between 0 and 255, inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// greater than or equal to the length of this object.
int getUint8(int byteOffset) native;
- /**
- * Sets the four bytes starting at the specified [byteOffset] in this
- * object to the IEEE 754 single-precision binary floating-point
- * (binary32) representation of the specified [value].
- *
- * **Note that this method can lose precision.** The input [value] is
- * a 64-bit floating point value, which will be converted to 32-bit
- * floating point value by IEEE 754 rounding rules before it is stored.
- * If [value] cannot be represented exactly as a binary32, it will be
- * converted to the nearest binary32 value. If two binary32 values are
- * equally close, the one whose least significant bit is zero will be used.
- * Note that finite (but large) values can be converted to infinity, and
- * small non-zero values can be converted to zero.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 4` is greater than the length of this object.
- */
+ /// Sets the four bytes starting at the specified [byteOffset] in this
+ /// object to the IEEE 754 single-precision binary floating-point
+ /// (binary32) representation of the specified [value].
+ ///
+ /// **Note that this method can lose precision.** The input [value] is
+ /// a 64-bit floating point value, which will be converted to 32-bit
+ /// floating point value by IEEE 754 rounding rules before it is stored.
+ /// If [value] cannot be represented exactly as a binary32, it will be
+ /// converted to the nearest binary32 value. If two binary32 values are
+ /// equally close, the one whose least significant bit is zero will be used.
+ /// Note that finite (but large) values can be converted to infinity, and
+ /// small non-zero values can be converted to zero.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 4` is greater than the length of this object.
void setFloat32(int byteOffset, num value, [Endian endian = Endian.big]) =>
_setFloat32(byteOffset, value, Endian.little == endian);
@JSName('setFloat32')
void _setFloat32(int byteOffset, num value, [bool littleEndian]) native;
- /**
- * Sets the eight bytes starting at the specified [byteOffset] in this
- * object to the IEEE 754 double-precision binary floating-point
- * (binary64) representation of the specified [value].
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 8` is greater than the length of this object.
- */
+ /// Sets the eight bytes starting at the specified [byteOffset] in this
+ /// object to the IEEE 754 double-precision binary floating-point
+ /// (binary64) representation of the specified [value].
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 8` is greater than the length of this object.
void setFloat64(int byteOffset, num value, [Endian endian = Endian.big]) =>
_setFloat64(byteOffset, value, Endian.little == endian);
@JSName('setFloat64')
void _setFloat64(int byteOffset, num value, [bool littleEndian]) native;
- /**
- * Sets the two bytes starting at the specified [byteOffset] in this
- * object to the two's complement binary representation of the specified
- * [value], which must fit in two bytes. In other words, [value] must lie
- * between 2<sup>15</sup> and 2<sup>15</sup> - 1, inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 2` is greater than the length of this object.
- */
+ /// Sets the two bytes starting at the specified [byteOffset] in this
+ /// object to the two's complement binary representation of the specified
+ /// [value], which must fit in two bytes. In other words, [value] must lie
+ /// between 2<sup>15</sup> and 2<sup>15</sup> - 1, inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 2` is greater than the length of this object.
void setInt16(int byteOffset, int value, [Endian endian = Endian.big]) =>
_setInt16(byteOffset, value, Endian.little == endian);
@JSName('setInt16')
void _setInt16(int byteOffset, int value, [bool littleEndian]) native;
- /**
- * Sets the four bytes starting at the specified [byteOffset] in this
- * object to the two's complement binary representation of the specified
- * [value], which must fit in four bytes. In other words, [value] must lie
- * between 2<sup>31</sup> and 2<sup>31</sup> - 1, inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 4` is greater than the length of this object.
- */
+ /// Sets the four bytes starting at the specified [byteOffset] in this
+ /// object to the two's complement binary representation of the specified
+ /// [value], which must fit in four bytes. In other words, [value] must lie
+ /// between 2<sup>31</sup> and 2<sup>31</sup> - 1, inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 4` is greater than the length of this object.
void setInt32(int byteOffset, int value, [Endian endian = Endian.big]) =>
_setInt32(byteOffset, value, Endian.little == endian);
@JSName('setInt32')
void _setInt32(int byteOffset, int value, [bool littleEndian]) native;
- /**
- * Sets the eight bytes starting at the specified [byteOffset] in this
- * object to the two's complement binary representation of the specified
- * [value], which must fit in eight bytes. In other words, [value] must lie
- * between 2<sup>63</sup> and 2<sup>63</sup> - 1, inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 8` is greater than the length of this object.
- */
+ /// Sets the eight bytes starting at the specified [byteOffset] in this
+ /// object to the two's complement binary representation of the specified
+ /// [value], which must fit in eight bytes. In other words, [value] must lie
+ /// between 2<sup>63</sup> and 2<sup>63</sup> - 1, inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 8` is greater than the length of this object.
void setInt64(int byteOffset, int value, [Endian endian = Endian.big]) {
throw new UnsupportedError('Int64 accessor not supported by dart2js.');
}
- /**
- * Sets the byte at the specified [byteOffset] in this object to the
- * two's complement binary representation of the specified [value], which
- * must fit in a single byte. In other words, [value] must be between
- * -128 and 127, inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * greater than or equal to the length of this object.
- */
+ /// Sets the byte at the specified [byteOffset] in this object to the
+ /// two's complement binary representation of the specified [value], which
+ /// must fit in a single byte. In other words, [value] must be between
+ /// -128 and 127, inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// greater than or equal to the length of this object.
void setInt8(int byteOffset, int value) native;
- /**
- * Sets the two bytes starting at the specified [byteOffset] in this object
- * to the unsigned binary representation of the specified [value],
- * which must fit in two bytes. in other words, [value] must be between
- * 0 and 2<sup>16</sup> - 1, inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 2` is greater than the length of this object.
- */
+ /// Sets the two bytes starting at the specified [byteOffset] in this object
+ /// to the unsigned binary representation of the specified [value],
+ /// which must fit in two bytes. in other words, [value] must be between
+ /// 0 and 2<sup>16</sup> - 1, inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 2` is greater than the length of this object.
void setUint16(int byteOffset, int value, [Endian endian = Endian.big]) =>
_setUint16(byteOffset, value, Endian.little == endian);
@JSName('setUint16')
void _setUint16(int byteOffset, int value, [bool littleEndian]) native;
- /**
- * Sets the four bytes starting at the specified [byteOffset] in this object
- * to the unsigned binary representation of the specified [value],
- * which must fit in four bytes. in other words, [value] must be between
- * 0 and 2<sup>32</sup> - 1, inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 4` is greater than the length of this object.
- */
+ /// Sets the four bytes starting at the specified [byteOffset] in this object
+ /// to the unsigned binary representation of the specified [value],
+ /// which must fit in four bytes. in other words, [value] must be between
+ /// 0 and 2<sup>32</sup> - 1, inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 4` is greater than the length of this object.
void setUint32(int byteOffset, int value, [Endian endian = Endian.big]) =>
_setUint32(byteOffset, value, Endian.little == endian);
@JSName('setUint32')
void _setUint32(int byteOffset, int value, [bool littleEndian]) native;
- /**
- * Sets the eight bytes starting at the specified [byteOffset] in this object
- * to the unsigned binary representation of the specified [value],
- * which must fit in eight bytes. in other words, [value] must be between
- * 0 and 2<sup>64</sup> - 1, inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative, or
- * `byteOffset + 8` is greater than the length of this object.
- */
+ /// Sets the eight bytes starting at the specified [byteOffset] in this object
+ /// to the unsigned binary representation of the specified [value],
+ /// which must fit in eight bytes. in other words, [value] must be between
+ /// 0 and 2<sup>64</sup> - 1, inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative, or
+ /// `byteOffset + 8` is greater than the length of this object.
void setUint64(int byteOffset, int value, [Endian endian = Endian.big]) {
throw new UnsupportedError('Uint64 accessor not supported by dart2js.');
}
- /**
- * Sets the byte at the specified [byteOffset] in this object to the
- * unsigned binary representation of the specified [value], which must fit
- * in a single byte. in other words, [value] must be between 0 and 255,
- * inclusive.
- *
- * Throws [RangeError] if [byteOffset] is negative,
- * or greater than or equal to the length of this object.
- */
+ /// Sets the byte at the specified [byteOffset] in this object to the
+ /// unsigned binary representation of the specified [value], which must fit
+ /// in a single byte. in other words, [value] must be between 0 and 255,
+ /// inclusive.
+ ///
+ /// Throws [RangeError] if [byteOffset] is negative,
+ /// or greater than or equal to the length of this object.
void setUint8(int byteOffset, int value) native;
static NativeByteData _create1(arg) =>
@@ -1159,11 +1087,9 @@
JS('NativeUint8List', 'new Uint8Array(#, #, #)', arg1, arg2, arg3);
}
-/**
- * Implementation of Dart Float32x4 immutable value type and operations.
- * Float32x4 stores 4 32-bit floating point values in "lanes".
- * The lanes are "x", "y", "z", and "w" respectively.
- */
+/// Implementation of Dart Float32x4 immutable value type and operations.
+/// Float32x4 stores 4 32-bit floating point values in "lanes".
+/// The lanes are "x", "y", "z", and "w" respectively.
class NativeFloat32x4 implements Float32x4 {
final double x;
final double y;
@@ -1494,11 +1420,9 @@
}
}
-/**
- * Interface of Dart Int32x4 and operations.
- * Int32x4 stores 4 32-bit bit-masks in "lanes".
- * The lanes are "x", "y", "z", and "w" respectively.
- */
+/// Interface of Dart Int32x4 and operations.
+/// Int32x4 stores 4 32-bit bit-masks in "lanes".
+/// The lanes are "x", "y", "z", and "w" respectively.
class NativeInt32x4 implements Int32x4 {
final int x;
final int y;
diff --git a/sdk/lib/_internal/js_runtime/lib/regexp_helper.dart b/sdk/lib/_internal/js_runtime/lib/regexp_helper.dart
index a588b08..77f746b 100644
--- a/sdk/lib/_internal/js_runtime/lib/regexp_helper.dart
+++ b/sdk/lib/_internal/js_runtime/lib/regexp_helper.dart
@@ -7,31 +7,27 @@
// Helper method used by internal libraries.
regExpGetNative(JSSyntaxRegExp regexp) => regexp._nativeRegExp;
-/**
- * Returns a native version of the RegExp with the global flag set.
- *
- * The RegExp's `lastIndex` property is zero when it is returned.
- *
- * The returned regexp is shared, and its `lastIndex` property may be
- * modified by other uses, so the returned regexp must be used immediately
- * when it's returned, with no user-provided code run in between.
- */
+/// Returns a native version of the RegExp with the global flag set.
+///
+/// The RegExp's `lastIndex` property is zero when it is returned.
+///
+/// The returned regexp is shared, and its `lastIndex` property may be
+/// modified by other uses, so the returned regexp must be used immediately
+/// when it's returned, with no user-provided code run in between.
regExpGetGlobalNative(JSSyntaxRegExp regexp) {
var nativeRegexp = regexp._nativeGlobalVersion;
JS('void', '#.lastIndex = 0', nativeRegexp);
return nativeRegexp;
}
-/**
- * Computes the number of captures in a regexp.
- *
- * This currently involves creating a new RegExp object with a different
- * source and running it against the empty string (the last part is usually
- * fast).
- *
- * The JSSyntaxRegExp could cache the result, and set the cache any time
- * it finds a match.
- */
+/// Computes the number of captures in a regexp.
+///
+/// This currently involves creating a new RegExp object with a different
+/// source and running it against the empty string (the last part is usually
+/// fast).
+///
+/// The JSSyntaxRegExp could cache the result, and set the cache any time
+/// it finds a match.
int regExpCaptureCount(JSSyntaxRegExp regexp) {
var nativeAnchoredRegExp = regexp._nativeAnchoredVersion;
var match = JS('JSExtendableArray', '#.exec("")', nativeAnchoredRegExp);
@@ -239,7 +235,7 @@
}
}
-/** Find the first match of [regExp] in [string] at or after [start]. */
+/// Find the first match of [regExp] in [string] at or after [start].
Match firstMatchAfter(JSSyntaxRegExp regExp, String string, int start) {
return regExp._execGlobal(string, start);
}
