diff --git a/sdk/lib/_internal/js_runtime/lib/convert_patch.dart b/sdk/lib/_internal/js_runtime/lib/convert_patch.dart index afb50626a82..a8dcc31229f 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:_internal' show MappedIterable, ListIterable; 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 @@ _parseJson(String source, reviver(key, value)) { } } -/** - * 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 @@ class JsonDecoder { } } -/** - * 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 2d0f53106e5..27d7d258662 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 @@ class _Uri { // 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 canonicalTable, String text, Encoding encoding, bool spaceToPlus) { @@ -879,12 +877,10 @@ int _min(int a, int b) => a < b ? a : b; * 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 @@ class _BigIntImpl implements BigInt { /// 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { /// 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 @@ class _BigIntImpl implements BigInt { 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 4f549a01e63..5377630836c 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 @@ library _foreign_helper; 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 `:;` where `` 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 `:;` where `` 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(String typeDescription, String codeTemplate, @@ -176,39 +175,31 @@ external T JS(String typeDescription, String codeTemplate, 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 @@ external JS_INTERCEPTOR_CONSTANT(Type type); /// 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 @@ external JS_BUILTIN(String typeDescription, JsBuiltin builtin, /// 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 287ec00b9a8..3344d39c537 100644 --- a/sdk/lib/_internal/js_runtime/lib/interceptors.dart +++ b/sdk/lib/_internal/js_runtime/lib/interceptors.dart @@ -123,10 +123,8 @@ dispatchRecordProto(record) => JS('', '#.p', record); 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 @@ void XcacheInterceptorOnConstructor(constructor, interceptor) { 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 @@ findInterceptorConstructorForType(Type type) { 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 @@ findInterceptorForType(Type type) { 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 @@ abstract class Interceptor { 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 @@ class JSBool extends Interceptor implements bool { 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 @@ class JSNull extends Interceptor implements Null { 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 { 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 extends JSIndexable { 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 @@ class JavaScriptObject extends Interceptor implements JSObject { 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 9d0a48ea6a6..c6956d99365 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 @@ class _Growable { 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 extends Interceptor implements List, JSIndexable { const JSArray(); @@ -28,11 +26,9 @@ class JSArray extends Interceptor implements List, JSIndexable { return new JSArray.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 @@ class JSArray extends Interceptor implements List, JSIndexable { return new JSArray.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.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 @@ class JSArray extends Interceptor implements List, JSIndexable { return new JSArray.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.typed(JS('JSExtendableArray', '[]')); - * a is List --> true - * a is List --> 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.typed(JS('JSExtendableArray', '[]')); + /// a is List --> true + /// a is List --> 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 @@ class JSArray extends Interceptor implements List, JSIndexable { 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 @@ class JSArray extends Interceptor implements List, JSIndexable { } } -/** - * 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 extends JSArray implements JSMutableIndexable {} class JSFixedArray extends JSMutableArray {} diff --git a/sdk/lib/_internal/js_runtime/lib/js_helper.dart b/sdk/lib/_internal/js_runtime/lib/js_helper.dart index 61e71827612..94571010929 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 @@ class Primitives { 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 @@ class Primitives { 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 namedArguments) { // Fast shortcut for the common case. @@ -1328,32 +1326,27 @@ class JsCache { } } -/** - * 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 @@ Error diagnoseIndexError(indexable, index) { 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 @@ checkString(value) { 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 @@ toStringWrapper() { 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 @@ throwConcurrentModificationError(collection) { 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 @@ class ExceptionAndStackTrace { 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 @@ String tryStringifyException(ex) { 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 @@ int objectHashCode(var object) { } } -/** - * 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 @@ invokeClosure(Function closure, int numberOfArguments, var arg1, var arg2, 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 @@ abstract class Closure implements Function { 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 @@ jsPropertyAccess(var jsObject, String property) { 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 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 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 @@ void propertyTypeCastError(value, property) { 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 @@ interceptedTypeCheck(value, property) { 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 @@ interceptedTypeCast(value, property) { 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 @@ numberOrStringSuperNativeTypeCast(value, property) { 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 @@ stringSuperNativeTypeCast(value, property) { 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 @@ void checkDeferredIsLoaded(String loadId, String uri) { } } -/** - * 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 extends JSMutableIndexable {} // 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 @@ class TypeErrorImplementation extends Error implements TypeError { 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 @@ class FallThroughErrorImplementation extends FallThroughError { 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 @@ bool assertTest(condition) { 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(), 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 @@ class UnimplementedNoSuchMethodError extends Error 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 @@ String jsonEncodeNative(String string) { 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 d3eaa07688e..572d354a695 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 @@ List extractKeys(victim) { 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 fed5dd854e7..1c030f393ea 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 @@ class JSNumber extends Interceptor implements double { 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 40c451c53c8..97577a0ca05 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 @@ library dart2js._js_primitives; 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 b5e84fab0e5..9a6ef994c17 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 @@ class TypeImpl implements Type { } } -/** - * 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 @@ getTypeArgumentByIndex(Object target, int index) { 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 @@ String _functionRtiToString(var rti, List genericContext) { 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 @@ String _joinArguments(var types, int startIndex, List genericContext) { 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 @@ Type getRuntimeType(var object) { 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 @@ substitute(var substitution, var arguments) { 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 @@ bool checkArguments( 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 @@ bool areSubtypes(var s, var sEnv, var t, var tEnv) { 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 @@ Object getFutureOrArgument(var type) { : 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 @@ Object assertSubtypeOfRuntimeType(Object object, var type) { 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 @@ bindInstantiatedTypes(rti, parameters, int depth) { 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 @@ bool isJsFunction(var o) => JS('bool', r'typeof # == "function"', o); /// 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 91e9734c148..baa47b6798c 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 @@ class JSString extends Interceptor implements String, JSIndexable { // 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 68bae9ad815..a3d3fc95654 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 @@ class _JSRandom implements Random { 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 fa111123351..59a371960e7 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 @@ getPropertyFromPrototype(var object, String name) { 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 @@ String toStringForNativeObject(var obj) { 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 @@ bool isDartObject(obj) { '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 @@ String findDispatchTagForInterceptorClass(interceptorClassConstructor) { '', 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 @@ const INTERIOR_MARK = '+'; /// 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 @@ makeDefaultDispatchRecord(tag, interceptorClass, proto) { } } -/** - * [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 @@ void initNativeDispatchContinue() { } } -/** - * 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 @@ function() { 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 7889c360843..9fa90706333 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 @@ class NativeByteBuffer implements ByteBuffer { } } -/** - * 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, FixedLengthListMixin 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 @@ class NativeFloat32x4List extends Object 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 list) { if (list is NativeFloat32x4List) { return new NativeFloat32x4List._externalStorage( @@ -178,20 +170,16 @@ class NativeFloat32x4List extends Object } } -/** - * 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, FixedLengthListMixin 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 @@ class NativeInt32x4List extends Object 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 list) { if (list is NativeInt32x4List) { return new NativeInt32x4List._externalStorage( @@ -256,20 +242,16 @@ class NativeInt32x4List extends Object } } -/** - * 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, FixedLengthListMixin 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 @@ class NativeFloat64x2List extends Object } } - /** - * 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 list) { if (list is NativeFloat64x2List) { return new NativeFloat64x2List._externalStorage( @@ -331,30 +311,22 @@ class NativeFloat64x2List extends Object @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 @@ List _ensureNativeList(List list) { @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 @@ class NativeByteData extends NativeTypedData implements ByteData { 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 @@ class NativeByteData extends NativeTypedData implements ByteData { @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 @@ class NativeByteData extends NativeTypedData implements ByteData { @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 215 and 215 - 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 215 and 215 - 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 @@ class NativeByteData extends NativeTypedData implements ByteData { @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 231 and 231 - 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 231 and 231 - 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 @@ class NativeByteData extends NativeTypedData implements ByteData { @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 263 and 263 - 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 263 and 263 - 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 216 - 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 216 - 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 @@ class NativeByteData extends NativeTypedData implements ByteData { @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 232 - 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 232 - 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 @@ class NativeByteData extends NativeTypedData implements ByteData { @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 264 - 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 264 - 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 215 and 215 - 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 215 and 215 - 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 231 and 231 - 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 231 and 231 - 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 263 and 263 - 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 263 and 263 - 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 216 - 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 216 - 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 232 - 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 232 - 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 264 - 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 264 - 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 @@ class NativeUint8List extends NativeTypedArrayOfInt implements Uint8List { 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 @@ class NativeFloat32x4 implements Float32x4 { } } -/** - * 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 a588b08cdc7..77f746b4e98 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 @@ part of _js_helper; // 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 @@ class _AllMatchesIterator implements Iterator { } } -/** 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); }