[dart2js] Run dartfmt --fix-doc-comments
Change-Id: I004a5da3f3e3adb5fc6f3088ba8dc3ca5082fbef
Reviewed-on: https://dart-review.googlesource.com/c/89163
Commit-Queue: Stephen Adams <sra@google.com>
Reviewed-by: Sigmund Cherem <sigmund@google.com>
diff --git a/pkg/compiler/lib/src/compiler.dart b/pkg/compiler/lib/src/compiler.dart
index 7a4326c..b35401a 100644
--- a/pkg/compiler/lib/src/compiler.dart
+++ b/pkg/compiler/lib/src/compiler.dart
@@ -443,9 +443,7 @@
return jClosedWorld;
}
- /**
- * Empty the [enqueuer] queue.
- */
+ /// Empty the [enqueuer] queue.
void emptyQueue(Enqueuer enqueuer, {void onProgress(Enqueuer enqueuer)}) {
selfTask.measureSubtask("emptyQueue", () {
enqueuer.forEach((WorkItem work) {
@@ -774,11 +772,9 @@
@override
bool get hasReportedError => compiler.compilationFailed;
- /**
- * Perform an operation, [f], returning the return value from [f]. If an
- * error occurs then report it as having occurred during compilation of
- * [element]. Can be nested.
- */
+ /// Perform an operation, [f], returning the return value from [f]. If an
+ /// error occurs then report it as having occurred during compilation of
+ /// [element]. Can be nested.
withCurrentElement(Entity element, f()) {
Entity old = currentElement;
_currentElement = element;
diff --git a/pkg/compiler/lib/src/constant_system_dart.dart b/pkg/compiler/lib/src/constant_system_dart.dart
index 8d9fab5..1fc88a5 100644
--- a/pkg/compiler/lib/src/constant_system_dart.dart
+++ b/pkg/compiler/lib/src/constant_system_dart.dart
@@ -51,9 +51,7 @@
}
}
-/**
- * Operations that only work if both arguments are integers.
- */
+/// Operations that only work if both arguments are integers.
abstract class BinaryBitOperation implements BinaryOperation {
const BinaryBitOperation();
ConstantValue fold(ConstantValue left, ConstantValue right) {
@@ -412,12 +410,10 @@
}
}
-/**
- * A constant system implementing the Dart semantics. This system relies on
- * the underlying runtime-system. That is, if dart2js is run in an environment
- * that doesn't correctly implement Dart's semantics this constant system will
- * not return the correct values.
- */
+/// A constant system implementing the Dart semantics. This system relies on
+/// the underlying runtime-system. That is, if dart2js is run in an environment
+/// that doesn't correctly implement Dart's semantics this constant system will
+/// not return the correct values.
class DartConstantSystem extends ConstantSystem {
final add = const AddOperation();
final bitAnd = const BitAndOperation();
diff --git a/pkg/compiler/lib/src/constants/constant_system.dart b/pkg/compiler/lib/src/constants/constant_system.dart
index c543720..91d89f2 100644
--- a/pkg/compiler/lib/src/constants/constant_system.dart
+++ b/pkg/compiler/lib/src/constants/constant_system.dart
@@ -14,19 +14,17 @@
}
abstract class UnaryOperation extends Operation {
- /** Returns [:null:] if it was unable to fold the operation. */
+ /// Returns [:null:] if it was unable to fold the operation.
ConstantValue fold(ConstantValue constant);
}
abstract class BinaryOperation extends Operation {
- /** Returns [:null:] if it was unable to fold the operation. */
+ /// Returns [:null:] if it was unable to fold the operation.
ConstantValue fold(ConstantValue left, ConstantValue right);
apply(left, right);
}
-/**
- * A [ConstantSystem] is responsible for creating constants and folding them.
- */
+/// A [ConstantSystem] is responsible for creating constants and folding them.
abstract class ConstantSystem {
BinaryOperation get add;
BinaryOperation get bitAnd;
@@ -75,15 +73,19 @@
// system because an int is a double at runtime.
bool isSubtype(DartTypes types, DartType s, DartType t);
- /** Returns true if the [constant] is an integer at runtime. */
+ /// Returns true if the [constant] is an integer at runtime.
bool isInt(ConstantValue constant);
- /** Returns true if the [constant] is a double at runtime. */
+
+ /// Returns true if the [constant] is a double at runtime.
bool isDouble(ConstantValue constant);
- /** Returns true if the [constant] is a string at runtime. */
+
+ /// Returns true if the [constant] is a string at runtime.
bool isString(ConstantValue constant);
- /** Returns true if the [constant] is a boolean at runtime. */
+
+ /// Returns true if the [constant] is a boolean at runtime.
bool isBool(ConstantValue constant);
- /** Returns true if the [constant] is null at runtime. */
+
+ /// Returns true if the [constant] is null at runtime.
bool isNull(ConstantValue constant);
UnaryOperation lookupUnary(UnaryOperator operator) {
diff --git a/pkg/compiler/lib/src/constants/values.dart b/pkg/compiler/lib/src/constants/values.dart
index aae0175..3d30d3b 100644
--- a/pkg/compiler/lib/src/constants/values.dart
+++ b/pkg/compiler/lib/src/constants/values.dart
@@ -71,9 +71,11 @@
bool get isMap => false;
bool get isConstructedObject => false;
bool get isFunction => false;
- /** Returns true if the constant is null, a bool, a number or a string. */
+
+ /// Returns true if the constant is null, a bool, a number or a string.
bool get isPrimitive => false;
- /** Returns true if the constant is a list, a map or a constructed object. */
+
+ /// Returns true if the constant is a list, a map or a constructed object.
bool get isObject => false;
bool get isType => false;
bool get isInterceptor => false;
@@ -170,7 +172,7 @@
}
class NullConstantValue extends PrimitiveConstantValue {
- /** The value a Dart null is compiled to in JavaScript. */
+ /// The value a Dart null is compiled to in JavaScript.
static const String JsNull = "null";
const factory NullConstantValue() = NullConstantValue._internal;
diff --git a/pkg/compiler/lib/src/dart2js.dart b/pkg/compiler/lib/src/dart2js.dart
index 4905ddb..dbfe890 100644
--- a/pkg/compiler/lib/src/dart2js.dart
+++ b/pkg/compiler/lib/src/dart2js.dart
@@ -23,21 +23,17 @@
const String _defaultSpecificationUri = '../../../../sdk/lib/libraries.json';
const String OUTPUT_LANGUAGE_DART = 'Dart';
-/**
- * A string to identify the revision or build.
- *
- * This ID is displayed if the compiler crashes and in verbose mode, and is
- * an aid in reproducing bug reports.
- *
- * The actual string is rewritten by a wrapper script when included in the sdk.
- */
+/// A string to identify the revision or build.
+///
+/// This ID is displayed if the compiler crashes and in verbose mode, and is
+/// an aid in reproducing bug reports.
+///
+/// The actual string is rewritten by a wrapper script when included in the sdk.
String BUILD_ID = null;
-/**
- * The data passed to the [HandleOption] callback is either a single
- * string argument, or the arguments iterator for multiple arguments
- * handlers.
- */
+/// The data passed to the [HandleOption] callback is either a single
+/// string argument, or the arguments iterator for multiple arguments
+/// handlers.
typedef void HandleOption(Null data);
class OptionHandler {
@@ -52,12 +48,10 @@
OptionHandler(this.pattern, this._handle, {this.multipleArguments: false});
}
-/**
- * Extract the parameter of an option.
- *
- * For example, in ['--out=fisk.js'] and ['-ohest.js'], the parameters
- * are ['fisk.js'] and ['hest.js'], respectively.
- */
+/// Extract the parameter of an option.
+///
+/// For example, in ['--out=fisk.js'] and ['-ohest.js'], the parameters
+/// are ['fisk.js'] and ['hest.js'], respectively.
String extractParameter(String argument, {bool isOptionalArgument: false}) {
// m[0] is the entire match (which will be equal to argument). m[1]
// is something like "-o" or "--out=", and m[2] is the parameter.
diff --git a/pkg/compiler/lib/src/diagnostics/messages.dart b/pkg/compiler/lib/src/diagnostics/messages.dart
index 31c1687..ddbd195 100644
--- a/pkg/compiler/lib/src/diagnostics/messages.dart
+++ b/pkg/compiler/lib/src/diagnostics/messages.dart
@@ -133,14 +133,12 @@
/// Should describe how to fix the problem. Elided when using --terse option.
final String howToFix;
- /**
- * Examples will be checked by
- * tests/compiler/dart2js/message_kind_test.dart.
- *
- * An example is either a String containing the example source code or a Map
- * from filenames to source code. In the latter case, the filename for the
- * main library code must be 'main.dart'.
- */
+ /// Examples will be checked by
+ /// tests/compiler/dart2js/message_kind_test.dart.
+ ///
+ /// An example is either a String containing the example source code or a Map
+ /// from filenames to source code. In the latter case, the filename for the
+ /// main library code must be 'main.dart'.
final List examples;
/// Additional options needed for the examples to work.
diff --git a/pkg/compiler/lib/src/diagnostics/spannable.dart b/pkg/compiler/lib/src/diagnostics/spannable.dart
index 3c8b6d1..cdba684 100644
--- a/pkg/compiler/lib/src/diagnostics/spannable.dart
+++ b/pkg/compiler/lib/src/diagnostics/spannable.dart
@@ -4,9 +4,7 @@
library dart2js.diagnostics.spannable;
-/**
- * Tagging interface for classes from which source spans can be generated.
- */
+/// Tagging interface for classes from which source spans can be generated.
// TODO(johnniwinther): Find a better name.
// TODO(ahe): How about "Bolt"?
abstract class Spannable {}
diff --git a/pkg/compiler/lib/src/elements/entity_utils.dart b/pkg/compiler/lib/src/elements/entity_utils.dart
index 6096e4a..0a26700 100644
--- a/pkg/compiler/lib/src/elements/entity_utils.dart
+++ b/pkg/compiler/lib/src/elements/entity_utils.dart
@@ -101,15 +101,13 @@
}
}
-/**
- * Map an operator-name to a valid JavaScript identifier.
- *
- * For non-operator names, this method just returns its input.
- *
- * The results returned from this method are guaranteed to be valid
- * JavaScript identifiers, except it may include reserved words for
- * non-operator names.
- */
+/// Map an operator-name to a valid JavaScript identifier.
+///
+/// For non-operator names, this method just returns its input.
+///
+/// The results returned from this method are guaranteed to be valid
+/// JavaScript identifiers, except it may include reserved words for
+/// non-operator names.
String operatorNameToIdentifier(String name) {
if (name == null) {
return name;
diff --git a/pkg/compiler/lib/src/elements/types.dart b/pkg/compiler/lib/src/elements/types.dart
index bc4d20e..d42f31a 100644
--- a/pkg/compiler/lib/src/elements/types.dart
+++ b/pkg/compiler/lib/src/elements/types.dart
@@ -103,7 +103,8 @@
bool _containsFreeTypeVariables(List<FunctionTypeVariable> bindings) => false;
}
-/// Pairs of [FunctionTypeVariable]s that are currently assumed to be equivalent.
+/// Pairs of [FunctionTypeVariable]s that are currently assumed to be
+/// equivalent.
///
/// This is used to compute the equivalence relation on types coinductively.
class _Assumptions {
diff --git a/pkg/compiler/lib/src/helpers/expensive_map.dart b/pkg/compiler/lib/src/helpers/expensive_map.dart
index 5f5cb44..ed95b22 100644
--- a/pkg/compiler/lib/src/helpers/expensive_map.dart
+++ b/pkg/compiler/lib/src/helpers/expensive_map.dart
@@ -4,11 +4,9 @@
import "dart:collection";
-/**
- * The expensive map is a data structure useful for tracking down
- * excessive memory usage due to large maps. It acts as an ordinary
- * hash map, but it uses 10 times more memory (by default).
- */
+/// The expensive map is a data structure useful for tracking down
+/// excessive memory usage due to large maps. It acts as an ordinary
+/// hash map, but it uses 10 times more memory (by default).
class ExpensiveMap<K, V> extends MapBase<K, V> {
final List _maps;
diff --git a/pkg/compiler/lib/src/helpers/expensive_set.dart b/pkg/compiler/lib/src/helpers/expensive_set.dart
index 76f8cd7..f4c2f4f 100644
--- a/pkg/compiler/lib/src/helpers/expensive_set.dart
+++ b/pkg/compiler/lib/src/helpers/expensive_set.dart
@@ -4,11 +4,9 @@
import 'dart:collection';
-/**
- * The expensive set is a data structure useful for tracking down
- * excessive memory usage due to large sets. It acts as an ordinary
- * hash set, but it uses 10 times more memory (by default).
- */
+/// The expensive set is a data structure useful for tracking down
+/// excessive memory usage due to large sets. It acts as an ordinary
+/// hash set, but it uses 10 times more memory (by default).
class ExpensiveSet<E> extends SetBase<E> {
final List _sets;
diff --git a/pkg/compiler/lib/src/helpers/trace.dart b/pkg/compiler/lib/src/helpers/trace.dart
index 2c92824..104c227 100644
--- a/pkg/compiler/lib/src/helpers/trace.dart
+++ b/pkg/compiler/lib/src/helpers/trace.dart
@@ -9,23 +9,21 @@
typedef void Trace(String message,
{bool condition(String stackTrace), int limit, bool throwOnPrint});
-/**
- * Helper method for printing stack traces for debugging.
- *
- * [message] is printed as the header of the stack trace.
- *
- * If [condition] is provided, the stack trace is only printed if [condition]
- * returns [:true:] on the stack trace text. This can be used to filter the
- * printed stack traces based on their content. For instance only print stack
- * traces that contain specific paths.
- *
- * If [limit] is provided, the stack trace is limited to [limit] entries.
- *
- * If [throwOnPrint] is `true`, [message] will be thrown after the stack trace
- * has been printed. Together with [condition] this can be used to discover
- * unknown call-sites in tests by filtering known call-sites and throwning
- * otherwise.
- */
+/// Helper method for printing stack traces for debugging.
+///
+/// [message] is printed as the header of the stack trace.
+///
+/// If [condition] is provided, the stack trace is only printed if [condition]
+/// returns [:true:] on the stack trace text. This can be used to filter the
+/// printed stack traces based on their content. For instance only print stack
+/// traces that contain specific paths.
+///
+/// If [limit] is provided, the stack trace is limited to [limit] entries.
+///
+/// If [throwOnPrint] is `true`, [message] will be thrown after the stack trace
+/// has been printed. Together with [condition] this can be used to discover
+/// unknown call-sites in tests by filtering known call-sites and throwning
+/// otherwise.
Trace get trace {
enableDebugMode();
return _trace;
@@ -293,22 +291,20 @@
}
// TODO(johnniwinther): Use this format for --throw-on-error.
-/**
- * Converts the normal VM stack trace into a more compact and readable format.
- *
- * The output format is [: <file> . . . <lineNo>:<columnNo> <method> :] where
- * [: <file> :] is file name, [: <lineNo> :] is the line number,
- * [: <columnNo> :] is the column number, and [: <method> :] is the method name.
- *
- * If [rangeStart] and/or [rangeEnd] are provided, only the lines within the
- * range are included.
- * If [showColumnNo] is [:false:], the [: :<columnNo> :] part is omitted.
- * If [showDots] is [:true:], the space between [: <file> :] and [: <lineNo> :]
- * is padded with dots on every other line.
- * If [filePrefix] is provided, then for every file name thats starts with
- * [filePrefix] only the remainder is printed.
- * If [lambda] is non-null, anonymous closures are printed as [lambda].
- */
+/// Converts the normal VM stack trace into a more compact and readable format.
+///
+/// The output format is `<file> . . . <lineNo>:<columnNo> <method>` where
+/// `<file>` is file name, `<lineNo>` is the line number, `<columnNo>` is the
+/// column number, and `<method>` is the method name.
+///
+/// If [rangeStart] and/or [rangeEnd] are provided, only the lines within the
+/// range are included.
+/// If [showColumnNo] is `false`, the `:<columnNo>` part is omitted.
+/// If [showDots] is `true`, the space between `<file>` and `<lineNo>` is padded
+/// with dots on every other line.
+/// If [filePrefix] is provided, then for every file name thats starts with
+/// [filePrefix] only the remainder is printed.
+/// If [lambda] is non-null, anonymous closures are printed as [lambda].
String prettifyStackTrace(StackTrace stackTrace,
{int rangeStart,
int rangeEnd,
@@ -324,12 +320,10 @@
.prettify(showColumnNo: showColumnNo, showDots: showDots);
}
-/**
- * Pads (or truncates) [text] to the [intendedLength].
- *
- * If [padLeft] is [:true:] the text is padding inserted to the left of [text].
- * A repetition of the [dots] text is used for padding.
- */
+/// Pads (or truncates) [text] to the [intendedLength].
+///
+/// If [padLeft] is [:true:] the text is padding inserted to the left of [text].
+/// A repetition of the [dots] text is used for padding.
String pad(String text, int intendedLength,
{bool padLeft: false, String dots: ' '}) {
if (text.length == intendedLength) return text;
diff --git a/pkg/compiler/lib/src/helpers/track_map.dart b/pkg/compiler/lib/src/helpers/track_map.dart
index 7c2eb86..6cb7121 100644
--- a/pkg/compiler/lib/src/helpers/track_map.dart
+++ b/pkg/compiler/lib/src/helpers/track_map.dart
@@ -2,17 +2,15 @@
// 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.
-/**
- * The track map is a simple wrapper around a map that keeps track
- * of the 'final' size of maps grouped by description. It allows
- * determining the distribution of sizes for a specific allocation
- * site and it can be used like this:
- *
- * Map<String, int> map = new TrackMap<String, int>("my-map");
- *
- * After finishing the compilaton, the histogram of track map sizes
- * is printed but only when running in verbose mode.
- */
+/// The track map is a simple wrapper around a map that keeps track
+/// of the 'final' size of maps grouped by description. It allows
+/// determining the distribution of sizes for a specific allocation
+/// site and it can be used like this:
+///
+/// Map<String, int> map = new TrackMap<String, int>("my-map");
+///
+/// After finishing the compilaton, the histogram of track map sizes
+/// is printed but only when running in verbose mode.
class TrackMap<K, V> implements Map<K, V> {
final Map<K, V> _map;
final List _counts;
diff --git a/pkg/compiler/lib/src/inferrer/inferrer_engine.dart b/pkg/compiler/lib/src/inferrer/inferrer_engine.dart
index e029d4f..60ea7a3 100644
--- a/pkg/compiler/lib/src/inferrer/inferrer_engine.dart
+++ b/pkg/compiler/lib/src/inferrer/inferrer_engine.dart
@@ -310,10 +310,8 @@
GlobalTypeInferenceElementData dataOfMember(MemberEntity element) =>
_memberData[element] ??= new KernelGlobalTypeInferenceElementData();
- /**
- * Update [sideEffects] with the side effects of [callee] being
- * called with [selector].
- */
+ /// Update [sideEffects] with the side effects of [callee] being
+ /// called with [selector].
void updateSideEffects(SideEffectsBuilder sideEffectsBuilder,
Selector selector, MemberEntity callee) {
if (callee.isField) {
diff --git a/pkg/compiler/lib/src/inferrer/list_tracer.dart b/pkg/compiler/lib/src/inferrer/list_tracer.dart
index 7043105..dfe10a0 100644
--- a/pkg/compiler/lib/src/inferrer/list_tracer.dart
+++ b/pkg/compiler/lib/src/inferrer/list_tracer.dart
@@ -11,11 +11,9 @@
import 'node_tracer.dart';
import 'type_graph_nodes.dart';
-/**
- * A set of selector names that [List] implements, that we know do not
- * change the element type of the list, or let the list escape to code
- * that might change the element type.
- */
+/// A set of selector names that [List] implements, that we know do not
+/// change the element type of the list, or let the list escape to code
+/// that might change the element type.
Set<String> okListSelectorsSet = new Set<String>.from(const <String>[
// From Object.
'==',
@@ -137,11 +135,9 @@
ListTracerVisitor(tracedType, inferrer) : super(tracedType, inferrer);
- /**
- * Returns [true] if the analysis completed successfully, [false] if it
- * bailed out. In the former case, [assignments] holds a list of
- * [TypeInformation] nodes that flow into the element type of this list.
- */
+ /// Returns [true] if the analysis completed successfully, [false] if it
+ /// bailed out. In the former case, [assignments] holds a list of
+ /// [TypeInformation] nodes that flow into the element type of this list.
bool run() {
analyze();
ListTypeInformation list = tracedType;
diff --git a/pkg/compiler/lib/src/inferrer/locals_handler.dart b/pkg/compiler/lib/src/inferrer/locals_handler.dart
index cfe7f1c..aff2896 100644
--- a/pkg/compiler/lib/src/inferrer/locals_handler.dart
+++ b/pkg/compiler/lib/src/inferrer/locals_handler.dart
@@ -13,13 +13,11 @@
import 'inferrer_engine.dart';
import 'type_graph_nodes.dart';
-/**
- * A variable scope holds types for variables. It has a link to a
- * parent scope, but never changes the types in that parent. Instead,
- * updates to locals of a parent scope are put in the current scope.
- * The inferrer makes sure updates get merged into the parent scope,
- * once the control flow block has been visited.
- */
+/// A variable scope holds types for variables. It has a link to a
+/// parent scope, but never changes the types in that parent. Instead,
+/// updates to locals of a parent scope are put in the current scope.
+/// The inferrer makes sure updates get merged into the parent scope,
+/// once the control flow block has been visited.
class VariableScope {
/// The number of parent scopes of this scope.
///
@@ -241,9 +239,7 @@
}
}
-/**
- * Placeholder for inferred arguments types on sends.
- */
+/// Placeholder for inferred arguments types on sends.
class ArgumentsTypes extends IterableMixin<TypeInformation> {
final List<TypeInformation> positional;
final Map<String, TypeInformation> named;
@@ -317,9 +313,7 @@
}
}
-/**
- * Placeholder for inferred types of local variables.
- */
+/// Placeholder for inferred types of local variables.
class LocalsHandler {
final VariableScope _locals;
@@ -439,36 +433,34 @@
return this;
}
- /**
- * Merge all [LocalsHandler] in [handlers] into [:this:].
- *
- * If [keepOwnLocals] is true, the types of locals in this
- * [LocalsHandler] are being used in the merge. [keepOwnLocals]
- * should be true if this [LocalsHandler], the dominator of
- * all [handlers], also directly flows into the join point,
- * that is the code after all [handlers]. For example, consider:
- *
- * [: switch (...) {
- * case 1: ...; break;
- * }
- * :]
- *
- * The [LocalsHandler] at entry of the switch also flows into the
- * exit of the switch, because there is no default case. So the
- * types of locals at entry of the switch have to take part to the
- * merge.
- *
- * The above situation is also true for labeled statements like
- *
- * [: L: {
- * if (...) break;
- * ...
- * }
- * :]
- *
- * where [:this:] is the [LocalsHandler] for the paths through the
- * labeled statement that do not break out.
- */
+ /// Merge all [LocalsHandler] in [handlers] into [:this:].
+ ///
+ /// If [keepOwnLocals] is true, the types of locals in this
+ /// [LocalsHandler] are being used in the merge. [keepOwnLocals]
+ /// should be true if this [LocalsHandler], the dominator of
+ /// all [handlers], also directly flows into the join point,
+ /// that is the code after all [handlers]. For example, consider:
+ ///
+ /// [: switch (...) {
+ /// case 1: ...; break;
+ /// }
+ /// :]
+ ///
+ /// The [LocalsHandler] at entry of the switch also flows into the
+ /// exit of the switch, because there is no default case. So the
+ /// types of locals at entry of the switch have to take part to the
+ /// merge.
+ ///
+ /// The above situation is also true for labeled statements like
+ ///
+ /// [: L: {
+ /// if (...) break;
+ /// ...
+ /// }
+ /// :]
+ ///
+ /// where [:this:] is the [LocalsHandler] for the paths through the
+ /// labeled statement that do not break out.
LocalsHandler mergeAfterBreaks(
InferrerEngine inferrer, Iterable<LocalsHandler> handlers,
{bool keepOwnLocals: true}) {
diff --git a/pkg/compiler/lib/src/inferrer/map_tracer.dart b/pkg/compiler/lib/src/inferrer/map_tracer.dart
index 83ad71c..e9da06a 100644
--- a/pkg/compiler/lib/src/inferrer/map_tracer.dart
+++ b/pkg/compiler/lib/src/inferrer/map_tracer.dart
@@ -43,12 +43,10 @@
MapTracerVisitor(tracedType, inferrer) : super(tracedType, inferrer);
- /**
- * Returns [true] if the analysis completed successfully, [false]
- * if it bailed out. In the former case, [keyAssignments] and
- * [valueAssignments] hold a list of [TypeInformation] nodes that
- * flow into the key and value types of this map.
- */
+ /// Returns [true] if the analysis completed successfully, [false]
+ /// if it bailed out. In the former case, [keyAssignments] and
+ /// [valueAssignments] hold a list of [TypeInformation] nodes that
+ /// flow into the key and value types of this map.
bool run() {
analyze();
MapTypeInformation map = tracedType;
diff --git a/pkg/compiler/lib/src/inferrer/node_tracer.dart b/pkg/compiler/lib/src/inferrer/node_tracer.dart
index e88535a..e0abccf 100644
--- a/pkg/compiler/lib/src/inferrer/node_tracer.dart
+++ b/pkg/compiler/lib/src/inferrer/node_tracer.dart
@@ -249,11 +249,9 @@
}
}
- /**
- * Checks whether this is a call to a list adding method. The definition of
- * what list adding means has to stay in sync with
- * [isParameterOfListAddingMethod].
- */
+ /// Checks whether this is a call to a list adding method. The definition of
+ /// what list adding means has to stay in sync with
+ /// [isParameterOfListAddingMethod].
bool mightAddToContainer(DynamicCallSiteTypeInformation info) {
if (info.arguments == null) return false;
if (info.arguments.named.isNotEmpty) return false;
@@ -275,20 +273,16 @@
return currentUser == arguments[index];
}
- /**
- * Checks whether the call site flows the currentUser to the key argument of
- * an indexing setter. This must be kept in sync with
- * [isParameterOfMapAddingMethod].
- */
+ /// Checks whether the call site flows the currentUser to the key argument of
+ /// an indexing setter. This must be kept in sync with
+ /// [isParameterOfMapAddingMethod].
bool isIndexSetKey(DynamicCallSiteTypeInformation info) {
return isIndexSetArgument(info, 0);
}
- /**
- * Checks whether the call site flows the currentUser to the value argument of
- * an indexing setter. This must be kept in sync with
- * [isParameterOfListAddingMethod] and [isParameterOfMapAddingMethod].
- */
+ /// Checks whether the call site flows the currentUser to the value argument
+ /// of an indexing setter. This must be kept in sync with
+ /// [isParameterOfListAddingMethod] and [isParameterOfMapAddingMethod].
bool isIndexSetValue(DynamicCallSiteTypeInformation info) {
return isIndexSetArgument(info, 1);
}
@@ -398,11 +392,9 @@
}
}
- /**
- * Check whether element is the parameter of a list adding method.
- * The definition of what a list adding method is has to stay in sync with
- * [mightAddToContainer].
- */
+ /// Check whether element is the parameter of a list adding method.
+ /// The definition of what a list adding method is has to stay in sync with
+ /// [mightAddToContainer].
bool isParameterOfListAddingMethod(ParameterTypeInformation parameterInfo) {
if (!parameterInfo.isRegularParameter) return false;
if (parameterInfo.method.enclosingClass !=
@@ -413,11 +405,9 @@
return (name == '[]=') || (name == 'add') || (name == 'insert');
}
- /**
- * Check whether element is the parameter of a list adding method.
- * The definition of what a list adding method is has to stay in sync with
- * [isIndexSetKey] and [isIndexSetValue].
- */
+ /// Check whether element is the parameter of a list adding method.
+ /// The definition of what a list adding method is has to stay in sync with
+ /// [isIndexSetKey] and [isIndexSetValue].
bool isParameterOfMapAddingMethod(ParameterTypeInformation parameterInfo) {
if (!parameterInfo.isRegularParameter) return false;
if (parameterInfo.method.enclosingClass !=
diff --git a/pkg/compiler/lib/src/inferrer/type_graph_inferrer.dart b/pkg/compiler/lib/src/inferrer/type_graph_inferrer.dart
index 67f830a..d9f69ca 100644
--- a/pkg/compiler/lib/src/inferrer/type_graph_inferrer.dart
+++ b/pkg/compiler/lib/src/inferrer/type_graph_inferrer.dart
@@ -18,12 +18,10 @@
import 'type_graph_nodes.dart';
import 'types.dart';
-/**
- * A work queue for the inferrer. It filters out nodes that are tagged as
- * [TypeInformation.doNotEnqueue], as well as ensures through
- * [TypeInformation.inQueue] that a node is in the queue only once at
- * a time.
- */
+/// A work queue for the inferrer. It filters out nodes that are tagged as
+/// [TypeInformation.doNotEnqueue], as well as ensures through
+/// [TypeInformation.inQueue] that a node is in the queue only once at
+/// a time.
class WorkQueue {
final Queue<TypeInformation> queue = new Queue<TypeInformation>();
diff --git a/pkg/compiler/lib/src/inferrer/type_graph_nodes.dart b/pkg/compiler/lib/src/inferrer/type_graph_nodes.dart
index f614109..794e62d 100644
--- a/pkg/compiler/lib/src/inferrer/type_graph_nodes.dart
+++ b/pkg/compiler/lib/src/inferrer/type_graph_nodes.dart
@@ -21,22 +21,20 @@
import 'inferrer_engine.dart';
import 'type_system.dart';
-/**
- * Common class for all nodes in the graph. The current nodes are:
- *
- * - Concrete types
- * - Elements
- * - Call sites
- * - Narrowing instructions
- * - Phi instructions
- * - Containers (for lists)
- * - Type of the element in a container
- *
- * A node has a set of assignments and users. Assignments are used to
- * compute the type of the node ([TypeInformation.computeType]). Users are
- * added to the inferrer's work queue when the type of the node
- * changes.
- */
+/// Common class for all nodes in the graph. The current nodes are:
+///
+/// - Concrete types
+/// - Elements
+/// - Call sites
+/// - Narrowing instructions
+/// - Phi instructions
+/// - Containers (for lists)
+/// - Type of the element in a container
+///
+/// A node has a set of assignments and users. Assignments are used to
+/// compute the type of the node ([TypeInformation.computeType]). Users are
+/// added to the inferrer's work queue when the type of the node
+/// changes.
abstract class TypeInformation {
Set<TypeInformation> users;
var /* List|ParameterAssignments */ _assignments;
@@ -149,16 +147,12 @@
return abandonInferencing ? safeType(inferrer) : computeType(inferrer);
}
- /**
- * Computes a new type for this [TypeInformation] node depending on its
- * potentially updated inputs.
- */
+ /// Computes a new type for this [TypeInformation] node depending on its
+ /// potentially updated inputs.
AbstractValue computeType(InferrerEngine inferrer);
- /**
- * Returns an approximation for this [TypeInformation] node that is always
- * safe to use. Used when abandoning inference on a node.
- */
+ /// Returns an approximation for this [TypeInformation] node that is always
+ /// safe to use. Used when abandoning inference on a node.
AbstractValue safeType(InferrerEngine inferrer) {
return inferrer.types.dynamicType.type;
}
@@ -243,14 +237,12 @@
bool mightBePassedToFunctionApply = false;
}
-/**
- * Marker node used only during tree construction but not during actual type
- * refinement.
- *
- * Currently, this is used to give a type to an optional parameter even before
- * the corresponding default expression has been analyzed. See
- * [getDefaultTypeOfParameter] and [setDefaultTypeOfParameter] for details.
- */
+/// Marker node used only during tree construction but not during actual type
+/// refinement.
+///
+/// Currently, this is used to give a type to an optional parameter even before
+/// the corresponding default expression has been analyzed. See
+/// [getDefaultTypeOfParameter] and [setDefaultTypeOfParameter] for details.
class PlaceholderTypeInformation extends TypeInformation {
PlaceholderTypeInformation(
AbstractValueDomain abstractValueDomain, MemberTypeInformation context)
@@ -267,13 +259,11 @@
toString() => "Placeholder [$hashCode]";
}
-/**
- * Parameters of instance functions behave differently than other
- * elements because the inferrer may remove assignments. This happens
- * when the receiver of a dynamic call site can be refined
- * to a type where we know more about which instance method is being
- * called.
- */
+/// Parameters of instance functions behave differently than other
+/// elements because the inferrer may remove assignments. This happens
+/// when the receiver of a dynamic call site can be refined
+/// to a type where we know more about which instance method is being
+/// called.
class ParameterAssignments extends IterableBase<TypeInformation> {
final Map<TypeInformation, int> assignments = new Map<TypeInformation, int>();
@@ -314,33 +304,31 @@
String toString() => assignments.keys.toList().toString();
}
-/**
- * A node representing a resolved element of the component. The kind of
- * elements that need an [ElementTypeInformation] are:
- *
- * - Functions (including getters and setters)
- * - Constructors (factory or generative)
- * - Fields
- * - Parameters
- * - Local variables mutated in closures
- *
- * The [ElementTypeInformation] of a function and a constructor is its
- * return type.
- *
- * Note that a few elements of these kinds must be treated specially,
- * and they are dealt in [ElementTypeInformation.handleSpecialCases]:
- *
- * - Parameters of closures, `noSuchMethod` and `call` instance
- * methods: we currently do not infer types for those.
- *
- * - Fields and parameters being assigned by synthesized calls done by
- * the backend: we do not know what types the backend will use.
- *
- * - Native functions and fields: because native methods contain no Dart
- * code, and native fields do not have Dart assignments, we just
- * trust their type annotation.
- *
- */
+/// A node representing a resolved element of the component. The kind of
+/// elements that need an [ElementTypeInformation] are:
+///
+/// - Functions (including getters and setters)
+/// - Constructors (factory or generative)
+/// - Fields
+/// - Parameters
+/// - Local variables mutated in closures
+///
+/// The [ElementTypeInformation] of a function and a constructor is its
+/// return type.
+///
+/// Note that a few elements of these kinds must be treated specially,
+/// and they are dealt in [ElementTypeInformation.handleSpecialCases]:
+///
+/// - Parameters of closures, `noSuchMethod` and `call` instance
+/// methods: we currently do not infer types for those.
+///
+/// - Fields and parameters being assigned by synthesized calls done by
+/// the backend: we do not know what types the backend will use.
+///
+/// - Native functions and fields: because native methods contain no Dart
+/// code, and native fields do not have Dart assignments, we just
+/// trust their type annotation.
+///
abstract class ElementTypeInformation extends TypeInformation {
/// Marker to disable inference for closures in [handleSpecialCases].
bool disableInferenceForClosures = true;
@@ -360,42 +348,36 @@
String get debugName;
}
-/**
- * A node representing members in the broadest sense:
- *
- * - Functions
- * - Constructors
- * - Fields (also synthetic ones due to closures)
- * - Local functions (closures)
- *
- * These should never be created directly but instead are constructed by
- * the [ElementTypeInformation] factory.
- */
+/// A node representing members in the broadest sense:
+///
+/// - Functions
+/// - Constructors
+/// - Fields (also synthetic ones due to closures)
+/// - Local functions (closures)
+///
+/// These should never be created directly but instead are constructed by
+/// the [ElementTypeInformation] factory.
abstract class MemberTypeInformation extends ElementTypeInformation
with ApplyableTypeInformation {
final MemberEntity _member;
- /**
- * If [element] is a function, [closurizedCount] is the number of
- * times it is closurized. The value gets updated while inferring.
- */
+ /// If [element] is a function, [closurizedCount] is the number of
+ /// times it is closurized. The value gets updated while inferring.
int closurizedCount = 0;
// Strict `bool` value is computed in cleanup(). Also used as a flag to see if
// cleanup has been called.
bool _isCalledOnce = null;
- /**
- * This map contains the callers of [element]. It stores all unique call sites
- * to enable counting the global number of call sites of [element].
- *
- * A call site is either an AST [ast.Node], an [Element] (see uses of
- * [synthesizeForwardingCall] in [SimpleTypeInferrerVisitor]) or an IR
- * [ir.Node].
- *
- * The global information is summarized in [cleanup], after which [_callers]
- * is set to `null`.
- */
+ /// This map contains the callers of [element]. It stores all unique call
+ /// sites to enable counting the global number of call sites of [element].
+ ///
+ /// A call site is either an AST [ast.Node], an [Element] (see uses of
+ /// [synthesizeForwardingCall] in [SimpleTypeInferrerVisitor]) or an IR
+ /// [ir.Node].
+ ///
+ /// The global information is summarized in [cleanup], after which [_callers]
+ /// is set to `null`.
Map<MemberEntity, Setlet<Object>> _callers;
MemberTypeInformation._internal(
@@ -673,15 +655,13 @@
}
}
-/**
- * A node representing parameters:
- *
- * - Parameters
- * - Initializing formals
- *
- * These should never be created directly but instead are constructed by
- * the [ElementTypeInformation] factory.
- */
+/// A node representing parameters:
+///
+/// - Parameters
+/// - Initializing formals
+///
+/// These should never be created directly but instead are constructed by
+/// the [ElementTypeInformation] factory.
class ParameterTypeInformation extends ElementTypeInformation {
final Local _parameter;
final DartType _type;
@@ -872,16 +852,14 @@
throw new StateError('Unexpected call type $callType.');
}
-/**
- * A [CallSiteTypeInformation] is a call found in the AST, or a
- * synthesized call for implicit calls in Dart (such as forwarding
- * factories). The [_call] field is a [ast.Node] for the former, and an
- * [Element] for the latter.
- *
- * In the inferrer graph, [CallSiteTypeInformation] nodes do not have
- * any assignment. They rely on the [caller] field for static calls,
- * and [selector] and [receiver] fields for dynamic calls.
- */
+/// A [CallSiteTypeInformation] is a call found in the AST, or a
+/// synthesized call for implicit calls in Dart (such as forwarding
+/// factories). The [_call] field is a [ast.Node] for the former, and an
+/// [Element] for the latter.
+///
+/// In the inferrer graph, [CallSiteTypeInformation] nodes do not have
+/// any assignment. They rely on the [caller] field for static calls,
+/// and [selector] and [receiver] fields for dynamic calls.
abstract class CallSiteTypeInformation extends TypeInformation
with ApplyableTypeInformation {
final Object _call;
@@ -1069,15 +1047,13 @@
});
}
- /**
- * We optimize certain operations on the [int] class because we know more
- * about their return type than the actual Dart code. For example, we know int
- * + int returns an int. The Dart library code for [int.operator+] only says
- * it returns a [num].
- *
- * Returns the more precise TypeInformation, or `null` to defer to the library
- * code.
- */
+ /// We optimize certain operations on the [int] class because we know more
+ /// about their return type than the actual Dart code. For example, we know
+ /// int + int returns an int. The Dart library code for [int.operator+] only
+ /// says it returns a [num].
+ ///
+ /// Returns the more precise TypeInformation, or `null` to defer to the
+ /// library code.
TypeInformation handleIntrisifiedSelector(
Selector selector, AbstractValue mask, InferrerEngine inferrer) {
JClosedWorld closedWorld = inferrer.closedWorld;
@@ -1240,8 +1216,8 @@
return abstractValueDomain.getDictionaryValueForKey(
typeMask, key);
} else {
- // The typeMap is precise, so if we do not find the key, the lookup
- // will be [null] at runtime.
+ // The typeMap is precise, so if we do not find the key, the
+ // lookup will be [null] at runtime.
if (debug.VERBOSE) {
print("Dictionary lookup for $key yields [null].");
}
@@ -1364,16 +1340,14 @@
}
}
-/**
- * A [ConcreteTypeInformation] represents a type that needed
- * to be materialized during the creation of the graph. For example,
- * literals, [:this:] or [:super:] need a [ConcreteTypeInformation].
- *
- * [ConcreteTypeInformation] nodes have no assignment. Also, to save
- * on memory, we do not add users to [ConcreteTypeInformation] nodes,
- * because we know such node will never be refined to a different
- * type.
- */
+/// A [ConcreteTypeInformation] represents a type that needed
+/// to be materialized during the creation of the graph. For example,
+/// literals, [:this:] or [:super:] need a [ConcreteTypeInformation].
+///
+/// [ConcreteTypeInformation] nodes have no assignment. Also, to save
+/// on memory, we do not add users to [ConcreteTypeInformation] nodes,
+/// because we know such node will never be refined to a different
+/// type.
class ConcreteTypeInformation extends TypeInformation {
ConcreteTypeInformation(AbstractValue type) : super.untracked(type) {
this.isStable = true;
@@ -1447,25 +1421,23 @@
}
}
-/**
- * A [NarrowTypeInformation] narrows a [TypeInformation] to a type,
- * represented in [typeAnnotation].
- *
- * A [NarrowTypeInformation] node has only one assignment: the
- * [TypeInformation] it narrows.
- *
- * [NarrowTypeInformation] nodes are created for:
- *
- * - Code after `is` and `as` checks, where we have more information
- * on the type of the right hand side of the expression.
- *
- * - Code after a dynamic call, where we have more information on the
- * type of the receiver: it can only be of a class that holds a
- * potential target of this dynamic call.
- *
- * - In checked mode, after a type annotation, we have more
- * information on the type of a local.
- */
+/// A [NarrowTypeInformation] narrows a [TypeInformation] to a type,
+/// represented in [typeAnnotation].
+///
+/// A [NarrowTypeInformation] node has only one assignment: the
+/// [TypeInformation] it narrows.
+///
+/// [NarrowTypeInformation] nodes are created for:
+///
+/// - Code after `is` and `as` checks, where we have more information
+/// on the type of the right hand side of the expression.
+///
+/// - Code after a dynamic call, where we have more information on the
+/// type of the receiver: it can only be of a class that holds a
+/// potential target of this dynamic call.
+///
+/// - In checked mode, after a type annotation, we have more
+/// information on the type of a local.
class NarrowTypeInformation extends TypeInformation {
final AbstractValue typeAnnotation;
@@ -1506,14 +1478,12 @@
}
}
-/**
- * An [InferredTypeInformation] is a [TypeInformation] that
- * defaults to the dynamic type until it is marked as being
- * inferred, at which point it computes its type based on
- * its assignments.
- */
+/// An [InferredTypeInformation] is a [TypeInformation] that
+/// defaults to the dynamic type until it is marked as being
+/// inferred, at which point it computes its type based on
+/// its assignments.
abstract class InferredTypeInformation extends TypeInformation {
- /** Whether the element type in that container has been inferred. */
+ /// Whether the element type in that container has been inferred.
bool inferred = false;
InferredTypeInformation(AbstractValueDomain abstractValueDomain,
@@ -1532,26 +1502,22 @@
}
}
-/**
- * A [ListTypeInformation] is a [TypeInformation] created
- * for each `List` instantiations.
- */
+/// A [ListTypeInformation] is a [TypeInformation] created
+/// for each `List` instantiations.
class ListTypeInformation extends TypeInformation with TracedTypeInformation {
final ElementInContainerTypeInformation elementType;
- /** The container type before it is inferred. */
+ /// The container type before it is inferred.
final AbstractValue originalType;
- /** The length at the allocation site. */
+ /// The length at the allocation site.
final int originalLength;
- /** The length after the container has been traced. */
+ /// The length after the container has been traced.
int inferredLength;
- /**
- * Whether this list goes through a growable check.
- * We conservatively assume it does.
- */
+ /// Whether this list goes through a growable check.
+ /// We conservatively assume it does.
bool checksGrowable = true;
ListTypeInformation(
@@ -1600,10 +1566,8 @@
}
}
-/**
- * An [ElementInContainerTypeInformation] holds the common type of the
- * elements in a [ListTypeInformation].
- */
+/// An [ElementInContainerTypeInformation] holds the common type of the
+/// elements in a [ListTypeInformation].
class ElementInContainerTypeInformation extends InferredTypeInformation {
ElementInContainerTypeInformation(AbstractValueDomain abstractValueDomain,
MemberTypeInformation context, elementType)
@@ -1616,10 +1580,8 @@
}
}
-/**
- * A [MapTypeInformation] is a [TypeInformation] created
- * for maps.
- */
+/// A [MapTypeInformation] is a [TypeInformation] created
+/// for maps.
class MapTypeInformation extends TypeInformation with TracedTypeInformation {
// When in Dictionary mode, this map tracks the type of the values that
// have been assigned to a specific [String] key.
@@ -1777,10 +1739,8 @@
}
}
-/**
- * A [KeyInMapTypeInformation] holds the common type
- * for the keys in a [MapTypeInformation]
- */
+/// A [KeyInMapTypeInformation] holds the common type
+/// for the keys in a [MapTypeInformation]
class KeyInMapTypeInformation extends InferredTypeInformation {
KeyInMapTypeInformation(AbstractValueDomain abstractValueDomain,
MemberTypeInformation context, TypeInformation keyType)
@@ -1793,10 +1753,8 @@
String toString() => 'Key in Map $type';
}
-/**
- * A [ValueInMapTypeInformation] holds the common type
- * for the values in a [MapTypeInformation]
- */
+/// A [ValueInMapTypeInformation] holds the common type
+/// for the values in a [MapTypeInformation]
class ValueInMapTypeInformation extends InferredTypeInformation {
// [nonNull] is set to true if this value is known to be part of the map.
// Note that only values assigned to a specific key value in dictionary
@@ -1821,10 +1779,8 @@
String toString() => 'Value in Map $type';
}
-/**
- * A [PhiElementTypeInformation] is an union of
- * [ElementTypeInformation], that is local to a method.
- */
+/// A [PhiElementTypeInformation] is an union of
+/// [ElementTypeInformation], that is local to a method.
class PhiElementTypeInformation extends TypeInformation {
final ir.Node branchNode;
final Local variable;
@@ -1893,9 +1849,7 @@
}
}
-/**
- * Mixin for [TypeInformation] nodes that can bail out during tracing.
- */
+/// Mixin for [TypeInformation] nodes that can bail out during tracing.
abstract class TracedTypeInformation implements TypeInformation {
/// Set to false once analysis has succeeded.
bool bailedOut = true;
@@ -1905,19 +1859,16 @@
Set<TypeInformation> _flowsInto;
- /**
- * The set of [TypeInformation] nodes where values from the traced node could
- * flow in.
- */
+ /// The set of [TypeInformation] nodes where values from the traced node could
+ /// flow in.
Set<TypeInformation> get flowsInto {
return (_flowsInto == null)
? const ImmutableEmptySet<TypeInformation>()
: _flowsInto;
}
- /**
- * Adds [nodes] to the sets of values this [TracedTypeInformation] flows into.
- */
+ /// Adds [nodes] to the sets of values this [TracedTypeInformation] flows
+ /// into.
void addFlowsIntoTargets(Iterable<TypeInformation> nodes) {
if (_flowsInto == null) {
_flowsInto = nodes.toSet();
diff --git a/pkg/compiler/lib/src/inferrer/type_system.dart b/pkg/compiler/lib/src/inferrer/type_system.dart
index cff86a1..21c5316 100644
--- a/pkg/compiler/lib/src/inferrer/type_system.dart
+++ b/pkg/compiler/lib/src/inferrer/type_system.dart
@@ -43,9 +43,7 @@
bool checkClassEntity(ClassEntity cls);
}
-/**
- * The class [SimpleInferrerVisitor] will use when working on types.
- */
+/// The class [SimpleInferrerVisitor] will use when working on types.
class TypeSystem {
final JClosedWorld _closedWorld;
final TypeSystemStrategy strategy;
@@ -274,10 +272,8 @@
_abstractValueDomain, value, _abstractValueDomain.boolType);
}
- /**
- * Returns the least upper bound between [firstType] and
- * [secondType].
- */
+ /// Returns the least upper bound between [firstType] and
+ /// [secondType].
TypeInformation computeLUB(
TypeInformation firstType, TypeInformation secondType) {
if (firstType == null) return secondType;
@@ -291,22 +287,18 @@
_abstractValueDomain.union(firstType.type, secondType.type));
}
- /**
- * Returns `true` if `selector` should be updated to reflect the new
- * `receiverType`.
- */
+ /// Returns `true` if `selector` should be updated to reflect the new
+ /// `receiverType`.
bool selectorNeedsUpdate(TypeInformation info, AbstractValue mask) {
return info.type != mask;
}
- /**
- * Returns a new receiver type for this [selector] applied to
- * [receiverType].
- *
- * The option [isConditional] is true when [selector] was seen in a
- * conditional send (e.g. `a?.selector`), in which case the returned type may
- * be null.
- */
+ /// Returns a new receiver type for this [selector] applied to
+ /// [receiverType].
+ ///
+ /// The option [isConditional] is true when [selector] was seen in a
+ /// conditional send (e.g. `a?.selector`), in which case the returned type
+ /// may be null.
TypeInformation refineReceiver(
Selector selector, AbstractValue mask, TypeInformation receiver,
{bool isConditional}) {
@@ -333,11 +325,9 @@
return newType;
}
- /**
- * Returns the intersection between [type] and [annotation].
- * [isNullable] indicates whether the annotation implies a null
- * type.
- */
+ /// Returns the intersection between [type] and [annotation].
+ /// [isNullable] indicates whether the annotation implies a null
+ /// type.
TypeInformation narrowType(TypeInformation type, DartType annotation,
{bool isNullable: true}) {
if (annotation.treatAsDynamic) return type;
@@ -377,9 +367,7 @@
}
}
- /**
- * Returns the non-nullable type of [type].
- */
+ /// Returns the non-nullable type of [type].
TypeInformation narrowNotNull(TypeInformation type) {
if (_abstractValueDomain.isExact(type.type).isDefinitelyTrue) {
return type;
@@ -423,9 +411,7 @@
return typeInformation;
}
- /**
- * Returns the internal inferrer representation for [mask].
- */
+ /// Returns the internal inferrer representation for [mask].
ConcreteTypeInformation getConcreteTypeFor(AbstractValue mask) {
assert(mask != null);
return concreteTypes.putIfAbsent(mask, () {
@@ -558,9 +544,7 @@
return info.isConcrete ? info.type : mask;
}
- /**
- * Returns a new type that unions [firstInput] and [secondInput].
- */
+ /// Returns a new type that unions [firstInput] and [secondInput].
TypeInformation allocateDiamondPhi(
TypeInformation firstInput, TypeInformation secondInput) {
PhiElementTypeInformation result = new PhiElementTypeInformation(
@@ -582,10 +566,8 @@
return result;
}
- /**
- * Returns a new type for holding the potential types of [element].
- * [inputType] is the first incoming type of the phi.
- */
+ /// Returns a new type for holding the potential types of [element].
+ /// [inputType] is the first incoming type of the phi.
PhiElementTypeInformation allocatePhi(
ir.Node node, Local variable, TypeInformation inputType,
{bool isTry}) {
@@ -601,13 +583,11 @@
return _addPhi(node, variable, inputType, isTry);
}
- /**
- * Returns a new type for holding the potential types of [element].
- * [inputType] is the first incoming type of the phi. [allocateLoopPhi]
- * only differs from [allocatePhi] in that it allows the underlying
- * implementation of [TypeSystem] to differentiate Phi nodes due to loops
- * from other merging uses.
- */
+ /// Returns a new type for holding the potential types of [element].
+ /// [inputType] is the first incoming type of the phi. [allocateLoopPhi]
+ /// only differs from [allocatePhi] in that it allows the underlying
+ /// implementation of [TypeSystem] to differentiate Phi nodes due to loops
+ /// from other merging uses.
PhiElementTypeInformation allocateLoopPhi(
ir.Node node, Local variable, TypeInformation inputType,
{bool isTry}) {
@@ -615,12 +595,10 @@
return _addPhi(node, variable, inputType, isTry);
}
- /**
- * Simplies the phi representing [element] and of the type
- * [phiType]. For example, if this phi has one incoming input, an
- * implementation of this method could just return that incoming
- * input type.
- */
+ /// Simplies the phi representing [element] and of the type
+ /// [phiType]. For example, if this phi has one incoming input, an
+ /// implementation of this method could just return that incoming
+ /// input type.
TypeInformation simplifyPhi(
ir.Node node, Local variable, PhiElementTypeInformation phiType) {
assert(phiType.branchNode == node);
@@ -628,9 +606,7 @@
return phiType;
}
- /**
- * Adds [newType] as an input of [phiType].
- */
+ /// Adds [newType] as an input of [phiType].
PhiElementTypeInformation addPhiInput(Local variable,
PhiElementTypeInformation phiType, TypeInformation newType) {
phiType.addAssignment(newType);
diff --git a/pkg/compiler/lib/src/inferrer/typemasks/dictionary_type_mask.dart b/pkg/compiler/lib/src/inferrer/typemasks/dictionary_type_mask.dart
index 8b67ca6..8463350 100644
--- a/pkg/compiler/lib/src/inferrer/typemasks/dictionary_type_mask.dart
+++ b/pkg/compiler/lib/src/inferrer/typemasks/dictionary_type_mask.dart
@@ -4,14 +4,12 @@
part of masks;
-/**
- * A [DictionaryTypeMask] is a [TypeMask] for a specific allocation
- * site of a map (currently only internal Map class) that is used as
- * a dictionary, i.e. a mapping from a set of statically known strings
- * to values. These typemasks only come into existence after the
- * [TypeGraphInferrer] has successfully identified such a usage. Otherwise,
- * the more general [MapTypeMask] is used.
- */
+/// A [DictionaryTypeMask] is a [TypeMask] for a specific allocation
+/// site of a map (currently only internal Map class) that is used as
+/// a dictionary, i.e. a mapping from a set of statically known strings
+/// to values. These typemasks only come into existence after the
+/// [TypeGraphInferrer] has successfully identified such a usage. Otherwise,
+/// the more general [MapTypeMask] is used.
class DictionaryTypeMask extends MapTypeMask {
/// Tag used for identifying serialized [DictionaryTypeMask] objects in a
/// debugging data stream.
diff --git a/pkg/compiler/lib/src/inferrer/typemasks/flat_type_mask.dart b/pkg/compiler/lib/src/inferrer/typemasks/flat_type_mask.dart
index 2dfe38a..41db5e8 100644
--- a/pkg/compiler/lib/src/inferrer/typemasks/flat_type_mask.dart
+++ b/pkg/compiler/lib/src/inferrer/typemasks/flat_type_mask.dart
@@ -4,10 +4,8 @@
part of masks;
-/**
- * A flat type mask is a type mask that has been flattened to contain a
- * base type.
- */
+/// A flat type mask is a type mask that has been flattened to contain a
+/// base type.
class FlatTypeMask implements TypeMask {
/// Tag used for identifying serialized [FlatTypeMask] objects in a
/// debugging data stream.
@@ -45,10 +43,8 @@
FlatTypeMask.internal(this.base, this.flags);
- /**
- * Ensures that the generated mask is normalized, i.e., a call to
- * [TypeMask.assertIsNormalized] with the factory's result returns `true`.
- */
+ /// Ensures that the generated mask is normalized, i.e., a call to
+ /// [TypeMask.assertIsNormalized] with the factory's result returns `true`.
factory FlatTypeMask.normalized(
ClassEntity base, int flags, JClosedWorld world) {
if ((flags >> 1) == EMPTY || ((flags >> 1) == EXACT)) {
@@ -260,9 +256,7 @@
}
}
- /**
- * Returns whether or not this type mask contains all types.
- */
+ /// Returns whether or not this type mask contains all types.
bool containsAll(JClosedWorld closedWorld) {
if (isEmptyOrNull || isExact) return false;
return identical(base, closedWorld.commonElements.objectClass);
@@ -519,11 +513,9 @@
: new TypeMask.nonNullEmpty();
}
- /**
- * Returns whether [element] is a potential target when being
- * invoked on this type mask. [selector] is used to ensure library
- * privacy is taken into account.
- */
+ /// Returns whether [element] is a potential target when being
+ /// invoked on this type mask. [selector] is used to ensure library
+ /// privacy is taken into account.
bool canHit(MemberEntity element, Name name, JClosedWorld closedWorld) {
CommonElements commonElements = closedWorld.commonElements;
assert(element.name == name.text);
diff --git a/pkg/compiler/lib/src/inferrer/typemasks/forwarding_type_mask.dart b/pkg/compiler/lib/src/inferrer/typemasks/forwarding_type_mask.dart
index 781a51e..7b8e73a 100644
--- a/pkg/compiler/lib/src/inferrer/typemasks/forwarding_type_mask.dart
+++ b/pkg/compiler/lib/src/inferrer/typemasks/forwarding_type_mask.dart
@@ -4,10 +4,8 @@
part of masks;
-/**
- * A type mask that wraps an other one, and delegate all its
- * implementation methods to it.
- */
+/// A type mask that wraps an other one, and delegate all its
+/// implementation methods to it.
abstract class ForwardingTypeMask implements TypeMask {
TypeMask get forwardTo;
diff --git a/pkg/compiler/lib/src/inferrer/typemasks/map_type_mask.dart b/pkg/compiler/lib/src/inferrer/typemasks/map_type_mask.dart
index 4a59fcd..2486256 100644
--- a/pkg/compiler/lib/src/inferrer/typemasks/map_type_mask.dart
+++ b/pkg/compiler/lib/src/inferrer/typemasks/map_type_mask.dart
@@ -4,11 +4,9 @@
part of masks;
-/**
- * A [MapTypeMask] is a [TypeMask] for a specific allocation
- * site of a map (currently only internal Map class) that will get specialized
- * once the [TypeGraphInferrer] phase finds a key and/or value type for it.
- */
+/// A [MapTypeMask] is a [TypeMask] for a specific allocation
+/// site of a map (currently only internal Map class) that will get specialized
+/// once the [TypeGraphInferrer] phase finds a key and/or value type for it.
class MapTypeMask extends AllocationTypeMask {
/// Tag used for identifying serialized [MapTypeMask] objects in a
/// debugging data stream.
diff --git a/pkg/compiler/lib/src/inferrer/typemasks/type_mask.dart b/pkg/compiler/lib/src/inferrer/typemasks/type_mask.dart
index eb06347..d54859d 100644
--- a/pkg/compiler/lib/src/inferrer/typemasks/type_mask.dart
+++ b/pkg/compiler/lib/src/inferrer/typemasks/type_mask.dart
@@ -103,11 +103,9 @@
value,
}
-/**
- * A type mask represents a set of contained classes, but the
- * operations on it are not guaranteed to be precise and they may
- * yield conservative answers that contain too many classes.
- */
+/// A type mask represents a set of contained classes, but the
+/// operations on it are not guaranteed to be precise and they may
+/// yield conservative answers that contain too many classes.
abstract class TypeMask implements AbstractValue {
factory TypeMask(
ClassEntity base, int kind, bool isNullable, JClosedWorld closedWorld) {
@@ -245,10 +243,8 @@
/// Serializes this [TypeMask] to [sink].
void writeToDataSink(DataSink sink);
- /**
- * If [mask] is forwarding, returns the first non-forwarding [TypeMask] in
- * [mask]'s forwarding chain.
- */
+ /// If [mask] is forwarding, returns the first non-forwarding [TypeMask] in
+ /// [mask]'s forwarding chain.
static TypeMask nonForwardingMask(mask) {
while (mask.isForwarding) {
mask = mask.forwardTo;
@@ -256,13 +252,11 @@
return mask;
}
- /**
- * Asserts that this mask uses the smallest possible representation for
- * its types. Currently, we normalize subtype and subclass to exact if no
- * subtypes or subclasses are present and subtype to subclass if only
- * subclasses exist. We also normalize exact to empty if the corresponding
- * baseclass was never instantiated.
- */
+ /// Asserts that this mask uses the smallest possible representation for
+ /// its types. Currently, we normalize subtype and subclass to exact if no
+ /// subtypes or subclasses are present and subtype to subclass if only
+ /// subclasses exist. We also normalize exact to empty if the corresponding
+ /// baseclass was never instantiated.
static bool assertIsNormalized(TypeMask mask, JClosedWorld closedWorld) {
String reason = getNotNormalizedReason(mask, closedWorld);
assert(reason == null,
@@ -307,14 +301,10 @@
return 'Unknown type mask $mask.';
}
- /**
- * Returns a nullable variant of [this] type mask.
- */
+ /// Returns a nullable variant of [this] type mask.
TypeMask nullable();
- /**
- * Returns a non-nullable variant of [this] type mask.
- */
+ /// Returns a non-nullable variant of [this] type mask.
TypeMask nonNullable();
/// Whether nothing matches this mask, not even null.
@@ -361,38 +351,28 @@
bool containsOnlyString(JClosedWorld closedWorld);
bool containsOnly(ClassEntity cls);
- /**
- * Compares two [TypeMask] objects for structural equality.
- *
- * Note: This may differ from semantic equality in the set containment sense.
- * Use [containsMask] and [isInMask] for that, instead.
- */
+ /// Compares two [TypeMask] objects for structural equality.
+ ///
+ /// Note: This may differ from semantic equality in the set containment sense.
+ /// Use [containsMask] and [isInMask] for that, instead.
bool operator ==(other);
- /**
- * If this returns `true`, [other] is guaranteed to be a supertype of this
- * mask, i.e., this mask is in [other]. However, the inverse does not hold.
- * Enable [UnionTypeMask.PERFORM_EXTRA_CONTAINS_CHECK] to be notified of
- * false negatives.
- */
+ /// If this returns `true`, [other] is guaranteed to be a supertype of this
+ /// mask, i.e., this mask is in [other]. However, the inverse does not hold.
+ /// Enable [UnionTypeMask.PERFORM_EXTRA_CONTAINS_CHECK] to be notified of
+ /// false negatives.
bool isInMask(TypeMask other, JClosedWorld closedWorld);
- /**
- * If this returns `true`, [other] is guaranteed to be a subtype of this mask,
- * i.e., this mask contains [other]. However, the inverse does not hold.
- * Enable [UnionTypeMask.PERFORM_EXTRA_CONTAINS_CHECK] to be notified of
- * false negatives.
- */
+ /// If this returns `true`, [other] is guaranteed to be a subtype of this
+ /// mask, i.e. this mask contains [other]. However, the inverse does not hold.
+ /// Enable [UnionTypeMask.PERFORM_EXTRA_CONTAINS_CHECK] to be notified of
+ /// false negatives.
bool containsMask(TypeMask other, JClosedWorld closedWorld);
- /**
- * Returns whether this type mask is an instance of [cls].
- */
+ /// Returns whether this type mask is an instance of [cls].
bool satisfies(ClassEntity cls, JClosedWorld closedWorld);
- /**
- * Returns whether or not this type mask contains the given class [cls].
- */
+ /// Returns whether or not this type mask contains the given class [cls].
bool contains(ClassEntity cls, JClosedWorld closedWorld);
/// Returns whether or not this type mask contains all types.
@@ -402,17 +382,13 @@
/// otherwise returns `null`. This method is conservative.
ClassEntity singleClass(JClosedWorld closedWorld);
- /**
- * Returns a type mask representing the union of [this] and [other].
- */
+ /// Returns a type mask representing the union of [this] and [other].
TypeMask union(TypeMask other, JClosedWorld closedWorld);
/// Returns whether the intersection of this and [other] is empty.
bool isDisjoint(TypeMask other, JClosedWorld closedWorld);
- /**
- * Returns a type mask representing the intersection of [this] and [other].
- */
+ /// Returns a type mask representing the intersection of [this] and [other].
TypeMask intersection(TypeMask other, JClosedWorld closedWorld);
/// Returns whether [element] is a potential target when being invoked on this
@@ -423,9 +399,7 @@
/// [noSuchMethod].
bool needsNoSuchMethodHandling(Selector selector, JClosedWorld world);
- /**
- * Returns the [element] that is known to always be hit at runtime
- * on this mask. Returns null if there is none.
- */
+ /// Returns the [element] that is known to always be hit at runtime
+ /// on this mask. Returns null if there is none.
MemberEntity locateSingleMember(Selector selector, JClosedWorld closedWorld);
}
diff --git a/pkg/compiler/lib/src/inferrer/typemasks/union_type_mask.dart b/pkg/compiler/lib/src/inferrer/typemasks/union_type_mask.dart
index 0d252f0..2f1f9de 100644
--- a/pkg/compiler/lib/src/inferrer/typemasks/union_type_mask.dart
+++ b/pkg/compiler/lib/src/inferrer/typemasks/union_type_mask.dart
@@ -232,14 +232,12 @@
bool get isForwarding => false;
bool get isValue => false;
- /**
- * Checks whether [other] is contained in this union.
- *
- * Invariants:
- * - [other] may not be a [UnionTypeMask] itself
- * - the cheap test matching against individual members of [disjointMasks]
- * must have failed.
- */
+ /// Checks whether [other] is contained in this union.
+ ///
+ /// Invariants:
+ /// - [other] may not be a [UnionTypeMask] itself
+ /// - the cheap test matching against individual members of [disjointMasks]
+ /// must have failed.
bool slowContainsCheck(TypeMask other, JClosedWorld closedWorld) {
// Unions should never make it here.
assert(!other.isUnion);
diff --git a/pkg/compiler/lib/src/ir/static_type.dart b/pkg/compiler/lib/src/ir/static_type.dart
index 8cafb6f..9ddc390 100644
--- a/pkg/compiler/lib/src/ir/static_type.dart
+++ b/pkg/compiler/lib/src/ir/static_type.dart
@@ -1273,7 +1273,8 @@
// We cannot promote. No single type is most specific.
// TODO(johnniwinther): Compute implied types? For instance when the
// declared type is `Iterable<String>` and tested type is
- // `List<dynamic>` we could promote to the implied type `List<String>`.
+ // `List<dynamic>` we could promote to the implied type
+ // `List<String>`.
return null;
}
}
diff --git a/pkg/compiler/lib/src/js/js_debug.dart b/pkg/compiler/lib/src/js/js_debug.dart
index f58853e..d191491 100644
--- a/pkg/compiler/lib/src/js/js_debug.dart
+++ b/pkg/compiler/lib/src/js/js_debug.dart
@@ -52,9 +52,7 @@
openAndCloseNode(node, '${node.runtimeType}', {'value': node.value});
}
- /**
- * Pretty-prints given node tree into string.
- */
+ /// Pretty-prints given node tree into string.
static String prettyPrint(Node node) {
var p = new DebugPrinter();
node.accept(p);
diff --git a/pkg/compiler/lib/src/js_backend/backend.dart b/pkg/compiler/lib/src/js_backend/backend.dart
index cbd4d59..be118eb 100644
--- a/pkg/compiler/lib/src/js_backend/backend.dart
+++ b/pkg/compiler/lib/src/js_backend/backend.dart
@@ -313,9 +313,7 @@
CodeEmitterTask emitter;
- /**
- * The generated code as a js AST for compiled methods.
- */
+ /// The generated code as a js AST for compiled methods.
final Map<MemberEntity, jsAst.Expression> generatedCode =
<MemberEntity, jsAst.Expression>{};
@@ -327,9 +325,7 @@
return _namer;
}
- /**
- * Set of classes whose `operator ==` methods handle `null` themselves.
- */
+ /// Set of classes whose `operator ==` methods handle `null` themselves.
final Set<ClassEntity> specialOperatorEqClasses = new Set<ClassEntity>();
List<CompilerTask> get tasks {
@@ -700,11 +696,9 @@
NativeEnqueuer get nativeCodegenEnqueuer => _nativeCodegenEnqueuer;
- /**
- * Unit test hook that returns code of an element as a String.
- *
- * Invariant: [element] must be a declaration element.
- */
+ /// Unit test hook that returns code of an element as a String.
+ ///
+ /// Invariant: [element] must be a declaration element.
String getGeneratedCode(MemberEntity element) {
return jsAst.prettyPrint(generatedCode[element],
enableMinification: compiler.options.enableMinification);
@@ -717,10 +711,8 @@
return programSize;
}
- /**
- * Returns [:true:] if the checking of [type] is performed directly on the
- * object and not on an interceptor.
- */
+ /// Returns [:true:] if the checking of [type] is performed directly on the
+ /// object and not on an interceptor.
bool hasDirectCheckFor(CommonElements commonElements, DartType type) {
if (!type.isInterfaceType) return false;
InterfaceType interfaceType = type;
diff --git a/pkg/compiler/lib/src/js_backend/checked_mode_helpers.dart b/pkg/compiler/lib/src/js_backend/checked_mode_helpers.dart
index ed231cc..71bb262 100644
--- a/pkg/compiler/lib/src/js_backend/checked_mode_helpers.dart
+++ b/pkg/compiler/lib/src/js_backend/checked_mode_helpers.dart
@@ -154,12 +154,10 @@
new Map<String, CheckedModeHelper>.fromIterable(helpers,
key: (helper) => helper.name);
- /**
- * Returns the checked mode helper that will be needed to do a type check/type
- * cast on [type] at runtime. Note that this method is being called both by
- * the resolver with interface types (int, String, ...), and by the SSA
- * backend with implementation types (JSInt, JSString, ...).
- */
+ /// Returns the checked mode helper that will be needed to do a type
+ /// check/type cast on [type] at runtime. Note that this method is being
+ /// called both by the resolver with interface types (int, String, ...), and
+ /// by the SSA backend with implementation types (JSInt, JSString, ...).
CheckedModeHelper getCheckedModeHelper(
DartType type, CommonElements commonElements,
{bool typeCast}) {
@@ -167,11 +165,9 @@
typeCast: typeCast, nativeCheckOnly: false);
}
- /**
- * Returns the native checked mode helper that will be needed to do a type
- * check/type cast on [type] at runtime. If no native helper exists for
- * [type], [:null:] is returned.
- */
+ /// Returns the native checked mode helper that will be needed to do a type
+ /// check/type cast on [type] at runtime. If no native helper exists for
+ /// [type], [:null:] is returned.
CheckedModeHelper getNativeCheckedModeHelper(
DartType type, CommonElements commonElements,
{bool typeCast}) {
@@ -179,10 +175,9 @@
typeCast: typeCast, nativeCheckOnly: true);
}
- /**
- * Returns the checked mode helper for the type check/type cast for [type]. If
- * [nativeCheckOnly] is [:true:], only names for native helpers are returned.
- */
+ /// Returns the checked mode helper for the type check/type cast for
+ /// [type]. If [nativeCheckOnly] is [:true:], only names for native helpers
+ /// are returned.
CheckedModeHelper getCheckedModeHelperInternal(
DartType type, CommonElements commonElements,
{bool typeCast, bool nativeCheckOnly}) {
diff --git a/pkg/compiler/lib/src/js_backend/constant_emitter.dart b/pkg/compiler/lib/src/js_backend/constant_emitter.dart
index 7afba73..3fb4475 100644
--- a/pkg/compiler/lib/src/js_backend/constant_emitter.dart
+++ b/pkg/compiler/lib/src/js_backend/constant_emitter.dart
@@ -22,13 +22,11 @@
typedef jsAst.Expression _ConstantListGenerator(jsAst.Expression array);
-/**
- * Generates the JavaScript expressions for constants.
- *
- * It uses a given [constantReferenceGenerator] to reference nested constants
- * (if there are some). It is hence up to that function to decide which
- * constants should be inlined or not.
- */
+/// Generates the JavaScript expressions for constants.
+///
+/// It uses a given [constantReferenceGenerator] to reference nested constants
+/// (if there are some). It is hence up to that function to decide which
+/// constants should be inlined or not.
class ConstantEmitter implements ConstantValueVisitor<jsAst.Expression, Null> {
// Matches blank lines, comment lines and trailing comments that can't be part
// of a string.
@@ -45,11 +43,9 @@
final _ConstantReferenceGenerator constantReferenceGenerator;
final _ConstantListGenerator makeConstantList;
- /**
- * The given [constantReferenceGenerator] function must, when invoked with a
- * constant, either return a reference or return its literal expression if it
- * can be inlined.
- */
+ /// The given [constantReferenceGenerator] function must, when invoked with a
+ /// constant, either return a reference or return its literal expression if it
+ /// can be inlined.
ConstantEmitter(
this._options,
this._commonElements,
@@ -63,11 +59,9 @@
Emitter get _emitter => _task.emitter;
- /**
- * Constructs a literal expression that evaluates to the constant. Uses a
- * canonical name unless the constant can be emitted multiple times (as for
- * numbers and strings).
- */
+ /// Constructs a literal expression that evaluates to the constant. Uses a
+ /// canonical name unless the constant can be emitted multiple times (as for
+ /// numbers and strings).
jsAst.Expression generate(ConstantValue constant) {
return _visit(constant);
}
@@ -171,11 +165,9 @@
}
}
- /**
- * Write the contents of the quoted string to a [CodeBuffer] in
- * a form that is valid as JavaScript string literal content.
- * The string is assumed quoted by double quote characters.
- */
+ /// Write the contents of the quoted string to a [CodeBuffer] in
+ /// a form that is valid as JavaScript string literal content.
+ /// The string is assumed quoted by double quote characters.
@override
jsAst.Expression visitString(StringConstantValue constant, [_]) {
return js.escapedString(constant.stringValue, ascii: true);
diff --git a/pkg/compiler/lib/src/js_backend/constant_handler_javascript.dart b/pkg/compiler/lib/src/js_backend/constant_handler_javascript.dart
index d454cf3..6b9de6a 100644
--- a/pkg/compiler/lib/src/js_backend/constant_handler_javascript.dart
+++ b/pkg/compiler/lib/src/js_backend/constant_handler_javascript.dart
@@ -31,14 +31,12 @@
ConstantSystem get constantSystem => dartConstantSystem;
}
-/**
- * The [JavaScriptConstantCompiler] is used to keep track of compile-time
- * constants, initializations of global and static fields, and default values of
- * optional parameters for the JavaScript interpretation of constants.
- */
+/// The [JavaScriptConstantCompiler] is used to keep track of compile-time
+/// constants, initializations of global and static fields, and default values
+/// of optional parameters for the JavaScript interpretation of constants.
class JavaScriptConstantCompiler implements BackendConstantEnvironment {
// TODO(johnniwinther): Move this to the backend constant handler.
- /** Caches the statics where the initial value cannot be eagerly compiled. */
+ /// Caches the statics where the initial value cannot be eagerly compiled.
final Set<FieldEntity> lazyStatics = new Set<FieldEntity>();
JavaScriptConstantCompiler();
diff --git a/pkg/compiler/lib/src/js_backend/constant_system_javascript.dart b/pkg/compiler/lib/src/js_backend/constant_system_javascript.dart
index 8b0d237..21eabbf 100644
--- a/pkg/compiler/lib/src/js_backend/constant_system_javascript.dart
+++ b/pkg/compiler/lib/src/js_backend/constant_system_javascript.dart
@@ -28,10 +28,8 @@
}
}
-/**
- * In JavaScript we truncate the result to an unsigned 32 bit integer. Also, -0
- * is treated as if it was the integer 0.
- */
+/// In JavaScript we truncate the result to an unsigned 32 bit integer. Also, -0
+/// is treated as if it was the integer 0.
class JavaScriptBinaryBitOperation implements BinaryOperation {
final BinaryBitOperation dartBitOperation;
@@ -223,10 +221,8 @@
}
}
-/**
- * Constant system following the semantics for Dart code that has been
- * compiled to JavaScript.
- */
+/// Constant system following the semantics for Dart code that has been
+/// compiled to JavaScript.
class JavaScriptConstantSystem extends ConstantSystem {
final BITS32 = new BigInt.from(0xFFFFFFFF);
@@ -269,10 +265,8 @@
JavaScriptConstantSystem._internal();
- /**
- * Returns true if [value] will turn into NaN or infinity
- * at runtime.
- */
+ /// Returns true if [value] will turn into NaN or infinity
+ /// at runtime.
bool integerBecomesNanOrInfinity(BigInt value) {
double doubleValue = value.toDouble();
return doubleValue.isNaN || doubleValue.isInfinite;
@@ -411,13 +405,11 @@
}
class JavaScriptMapConstant extends MapConstantValue {
- /**
- * The [PROTO_PROPERTY] must not be used as normal property in any JavaScript
- * object. It would change the prototype chain.
- */
+ /// The [PROTO_PROPERTY] must not be used as normal property in any JavaScript
+ /// object. It would change the prototype chain.
static const String PROTO_PROPERTY = "__proto__";
- /** The dart class implementing constant map literals. */
+ /// The dart class implementing constant map literals.
static const String DART_CLASS = "ConstantMap";
static const String DART_STRING_CLASS = "ConstantStringMap";
static const String DART_PROTO_CLASS = "ConstantProtoMap";
diff --git a/pkg/compiler/lib/src/js_backend/custom_elements_analysis.dart b/pkg/compiler/lib/src/js_backend/custom_elements_analysis.dart
index 4b27e24..79a4453 100644
--- a/pkg/compiler/lib/src/js_backend/custom_elements_analysis.dart
+++ b/pkg/compiler/lib/src/js_backend/custom_elements_analysis.dart
@@ -14,43 +14,41 @@
import 'backend_usage.dart' show BackendUsageBuilder;
import 'native_data.dart';
-/**
- * Support for Custom Elements.
- *
- * The support for custom elements the compiler builds a table that maps the
- * custom element class's [Type] to the interceptor for the class and the
- * constructor(s) for the class.
- *
- * We want the table to contain only the custom element classes used, and we
- * want to avoid resolving and compiling constructors that are not used since
- * that may bring in unused code. This class controls the resolution and code
- * generation to restrict the impact.
- *
- * The following line of code requires the generation of the generative
- * constructor factory function(s) for FancyButton, and their insertion into the
- * table:
- *
- * document.register(FancyButton, 'x-fancy-button');
- *
- * We detect this by 'joining' the classes that are referenced as type literals
- * with the classes that are custom elements, enabled by detecting the presence
- * of the table access code used by document.register.
- *
- * We have to be more conservative when the type is unknown, e.g.
- *
- * document.register(classMirror.reflectedType, tagFromMetadata);
- *
- * and
- *
- * class Component<T> {
- * final tag;
- * Component(this.tag);
- * void register() => document.register(T, tag);
- * }
- * const Component<FancyButton>('x-fancy-button').register();
- *
- * In these cases we conservatively generate all viable entries in the table.
- */
+/// Support for Custom Elements.
+///
+/// The support for custom elements the compiler builds a table that maps the
+/// custom element class's [Type] to the interceptor for the class and the
+/// constructor(s) for the class.
+///
+/// We want the table to contain only the custom element classes used, and we
+/// want to avoid resolving and compiling constructors that are not used since
+/// that may bring in unused code. This class controls the resolution and code
+/// generation to restrict the impact.
+///
+/// The following line of code requires the generation of the generative
+/// constructor factory function(s) for FancyButton, and their insertion into
+/// the table:
+///
+/// document.register(FancyButton, 'x-fancy-button');
+///
+/// We detect this by 'joining' the classes that are referenced as type literals
+/// with the classes that are custom elements, enabled by detecting the presence
+/// of the table access code used by document.register.
+///
+/// We have to be more conservative when the type is unknown, e.g.
+///
+/// document.register(classMirror.reflectedType, tagFromMetadata);
+///
+/// and
+///
+/// class Component<T> {
+/// final tag;
+/// Component(this.tag);
+/// void register() => document.register(T, tag);
+/// }
+/// const Component<FancyButton>('x-fancy-button').register();
+///
+/// In these cases we conservatively generate all viable entries in the table.
abstract class CustomElementsAnalysisBase {
final NativeBasicData _nativeData;
final ElementEnvironment _elementEnvironment;
diff --git a/pkg/compiler/lib/src/js_backend/field_naming_mixin.dart b/pkg/compiler/lib/src/js_backend/field_naming_mixin.dart
index f7e8984..828dd25 100644
--- a/pkg/compiler/lib/src/js_backend/field_naming_mixin.dart
+++ b/pkg/compiler/lib/src/js_backend/field_naming_mixin.dart
@@ -33,13 +33,11 @@
}
}
-/**
- * Encapsulates the global state of field naming.
- *
- * The field naming registry allocates names to be used along a path in the
- * inheritance hierarchy of fields, starting with the object class. The actual
- * hierarchy is encoded using instances of [_FieldNamingScope].
- */
+/// Encapsulates the global state of field naming.
+///
+/// The field naming registry allocates names to be used along a path in the
+/// inheritance hierarchy of fields, starting with the object class. The actual
+/// hierarchy is encoded using instances of [_FieldNamingScope].
class _FieldNamingRegistry {
final Namer namer;
@@ -82,18 +80,16 @@
}
}
-/**
- * A [_FieldNamingScope] encodes a node in the inheritance tree of the current
- * class hierarchy. The root node typically is the node corresponding to the
- * `Object` class. It is used to assign a unique name to each field of a class.
- * Unique here means unique wrt. all fields along the path back to the root.
- * This is achieved at construction time via the [_fieldNameCounter] field that
- * counts the number of fields on the path to the root node that have been
- * encountered so far.
- *
- * Obviously, this only works if no fields are added to a parent node after its
- * children have added their first field.
- */
+/// A [_FieldNamingScope] encodes a node in the inheritance tree of the current
+/// class hierarchy. The root node typically is the node corresponding to the
+/// `Object` class. It is used to assign a unique name to each field of a class.
+/// Unique here means unique wrt. all fields along the path back to the root.
+/// This is achieved at construction time via the [_fieldNameCounter] field that
+/// counts the number of fields on the path to the root node that have been
+/// encountered so far.
+///
+/// Obviously, this only works if no fields are added to a parent node after its
+/// children have added their first field.
class _FieldNamingScope {
final _FieldNamingScope superScope;
final Entity container;
@@ -160,9 +156,7 @@
_fieldNameCounter = superScope.inheritanceBasedFieldNameCounter;
}
- /**
- * Checks whether [name] is already used in the current scope chain.
- */
+ /// Checks whether [name] is already used in the current scope chain.
_isNameUnused(jsAst.Name name) {
return !names.values.contains(name) &&
((superScope == null) || superScope._isNameUnused(name));
@@ -187,15 +181,13 @@
bool containsField(Entity field) => names.containsKey(field);
}
-/**
- * Field names for mixins have two constraints: They need to be unique in the
- * hierarchy of each application of a mixin and they need to be the same for
- * all applications of a mixin. To achieve this, we use global naming for
- * mixins from the same name pool as fields and add a `$` at the end to ensure
- * they do not collide with normal field names. The `$` sign is typically used
- * as a separator between method names and argument counts and does not appear
- * in generated names themselves.
- */
+/// Field names for mixins have two constraints: They need to be unique in the
+/// hierarchy of each application of a mixin and they need to be the same for
+/// all applications of a mixin. To achieve this, we use global naming for
+/// mixins from the same name pool as fields and add a `$` at the end to ensure
+/// they do not collide with normal field names. The `$` sign is typically used
+/// as a separator between method names and argument counts and does not appear
+/// in generated names themselves.
class _MixinFieldNamingScope extends _FieldNamingScope {
int get _localFieldNameCounter => registry.globalCount;
void set _localFieldNameCounter(int val) {
@@ -218,12 +210,10 @@
}
}
-/**
- * [BoxFieldElement] fields work differently in that they do not belong to an
- * actual class but an anonymous box associated to a [Local]. As there is no
- * inheritance chain, we do not need to compute fields a priori but can assign
- * names on the fly.
- */
+/// [BoxFieldElement] fields work differently in that they do not belong to an
+/// actual class but an anonymous box associated to a [Local]. As there is no
+/// inheritance chain, we do not need to compute fields a priori but can assign
+/// names on the fly.
class _BoxFieldNamingScope extends _FieldNamingScope {
_BoxFieldNamingScope(Local box, _FieldNamingRegistry registry)
: super.rootScope(box, registry);
diff --git a/pkg/compiler/lib/src/js_backend/minify_namer.dart b/pkg/compiler/lib/src/js_backend/minify_namer.dart
index 3739932..2d772ff 100644
--- a/pkg/compiler/lib/src/js_backend/minify_namer.dart
+++ b/pkg/compiler/lib/src/js_backend/minify_namer.dart
@@ -4,9 +4,7 @@
part of js_backend.namer;
-/**
- * Assigns JavaScript identifiers to Dart variables, class-names and members.
- */
+/// Assigns JavaScript identifiers to Dart variables, class-names and members.
class MinifyNamer extends Namer
with
_MinifiedFieldNamer,
diff --git a/pkg/compiler/lib/src/js_backend/namer.dart b/pkg/compiler/lib/src/js_backend/namer.dart
index 0fe5bd1..9e7a95b 100644
--- a/pkg/compiler/lib/src/js_backend/namer.dart
+++ b/pkg/compiler/lib/src/js_backend/namer.dart
@@ -40,103 +40,101 @@
part 'minify_namer.dart';
part 'namer_names.dart';
-/**
- * Assigns JavaScript identifiers to Dart variables, class-names and members.
- *
- * Names are generated through three stages:
- *
- * 1. Original names and proposed names
- * 2. Disambiguated names (also known as "mangled names")
- * 3. Annotated names
- *
- * Original names are names taken directly from the input.
- *
- * Proposed names are either original names or synthesized names for input
- * elements that do not have original names.
- *
- * Disambiguated names are derived from the above, but are mangled to ensure
- * uniqueness within some namespace (e.g. as fields on the same JS object).
- * In [MinifyNamer], disambiguated names are also minified.
- *
- * Annotated names are names generated from a disambiguated name. Annotated
- * names must be computable at runtime by prefixing/suffixing constant strings
- * onto the disambiguated name.
- *
- * For example, some entity called `x` might be associated with these names:
- *
- * Original name: `x`
- *
- * Disambiguated name: `x1` (if something else was called `x`)
- *
- * Annotated names: `x1` (field name)
- * `get$x1` (getter name)
- * `set$x1` (setter name)
- *
- * The [Namer] can choose the disambiguated names, and to some degree the
- * prefix/suffix constants used to construct annotated names. It cannot choose
- * annotated names with total freedom, for example, it cannot choose that the
- * getter for `x1` should be called `getX` -- the annotated names are always
- * built by concatenation.
- *
- * Disambiguated names must be chosen such that none of the annotated names can
- * clash with each other. This may happen even if the disambiguated names are
- * distinct, for example, suppose a field `x` and `get$x` exists in the input:
- *
- * Original names: `x` and `get$x`
- *
- * Disambiguated names: `x` and `get$x` (the two names a different)
- *
- * Annotated names: `x` (field for `x`)
- * `get$x` (getter for `x`)
- * `get$x` (field for `get$x`)
- * `get$get$x` (getter for `get$x`)
- *
- * The getter for `x` clashes with the field name for `get$x`, so the
- * disambiguated names are invalid.
- *
- * Additionally, disambiguated names must be chosen such that all annotated
- * names are valid JavaScript identifiers and do not coincide with a native
- * JavaScript property such as `__proto__`.
- *
- * The following annotated names are generated for instance members, where
- * <NAME> denotes the disambiguated name.
- *
- * 0. The disambiguated name can itself be seen as an annotated name.
- *
- * 1. Multiple annotated names exist for the `call` method, encoding arity and
- * named parameters with the pattern:
- *
- * call$<N>$namedParam1...$namedParam<M>
- *
- * where <N> is the number of parameters (required and optional) and <M> is
- * the number of named parameters, and namedParam<n> are the names of the
- * named parameters in alphabetical order.
- *
- * Note that the same convention is used for the *proposed name* of other
- * methods. Thus, for ordinary methods, the suffix becomes embedded in the
- * disambiguated name (and can be minified), whereas for the 'call' method,
- * the suffix is an annotation that must be computable at runtime
- * (and thus cannot be minified).
- *
- * Note that the ordering of named parameters is not encapsulated in the
- * [Namer], and is hardcoded into other components, such as [Element] and
- * [Selector].
- *
- * 2. The getter/setter for a field:
- *
- * get$<NAME>
- * set$<NAME>
- *
- * (The [getterPrefix] and [setterPrefix] are different in [MinifyNamer]).
- *
- * 3. The `is` and operator uses the following names:
- *
- * $is<NAME>
- * $as<NAME>
- *
- * For local variables, the [Namer] only provides *proposed names*. These names
- * must be disambiguated elsewhere.
- */
+/// Assigns JavaScript identifiers to Dart variables, class-names and members.
+///
+/// Names are generated through three stages:
+///
+/// 1. Original names and proposed names
+/// 2. Disambiguated names (also known as "mangled names")
+/// 3. Annotated names
+///
+/// Original names are names taken directly from the input.
+///
+/// Proposed names are either original names or synthesized names for input
+/// elements that do not have original names.
+///
+/// Disambiguated names are derived from the above, but are mangled to ensure
+/// uniqueness within some namespace (e.g. as fields on the same JS object).
+/// In [MinifyNamer], disambiguated names are also minified.
+///
+/// Annotated names are names generated from a disambiguated name. Annotated
+/// names must be computable at runtime by prefixing/suffixing constant strings
+/// onto the disambiguated name.
+///
+/// For example, some entity called `x` might be associated with these names:
+///
+/// Original name: `x`
+///
+/// Disambiguated name: `x1` (if something else was called `x`)
+///
+/// Annotated names: `x1` (field name)
+/// `get$x1` (getter name)
+/// `set$x1` (setter name)
+///
+/// The [Namer] can choose the disambiguated names, and to some degree the
+/// prefix/suffix constants used to construct annotated names. It cannot choose
+/// annotated names with total freedom, for example, it cannot choose that the
+/// getter for `x1` should be called `getX` -- the annotated names are always
+/// built by concatenation.
+///
+/// Disambiguated names must be chosen such that none of the annotated names can
+/// clash with each other. This may happen even if the disambiguated names are
+/// distinct, for example, suppose a field `x` and `get$x` exists in the input:
+///
+/// Original names: `x` and `get$x`
+///
+/// Disambiguated names: `x` and `get$x` (the two names a different)
+///
+/// Annotated names: `x` (field for `x`)
+/// `get$x` (getter for `x`)
+/// `get$x` (field for `get$x`)
+/// `get$get$x` (getter for `get$x`)
+///
+/// The getter for `x` clashes with the field name for `get$x`, so the
+/// disambiguated names are invalid.
+///
+/// Additionally, disambiguated names must be chosen such that all annotated
+/// names are valid JavaScript identifiers and do not coincide with a native
+/// JavaScript property such as `__proto__`.
+///
+/// The following annotated names are generated for instance members, where
+/// <NAME> denotes the disambiguated name.
+///
+/// 0. The disambiguated name can itself be seen as an annotated name.
+///
+/// 1. Multiple annotated names exist for the `call` method, encoding arity and
+/// named parameters with the pattern:
+///
+/// call$<N>$namedParam1...$namedParam<M>
+///
+/// where <N> is the number of parameters (required and optional) and <M> is
+/// the number of named parameters, and namedParam<n> are the names of the
+/// named parameters in alphabetical order.
+///
+/// Note that the same convention is used for the *proposed name* of other
+/// methods. Thus, for ordinary methods, the suffix becomes embedded in the
+/// disambiguated name (and can be minified), whereas for the 'call' method,
+/// the suffix is an annotation that must be computable at runtime
+/// (and thus cannot be minified).
+///
+/// Note that the ordering of named parameters is not encapsulated in the
+/// [Namer], and is hardcoded into other components, such as [Element] and
+/// [Selector].
+///
+/// 2. The getter/setter for a field:
+///
+/// get$<NAME>
+/// set$<NAME>
+///
+/// (The [getterPrefix] and [setterPrefix] are different in [MinifyNamer]).
+///
+/// 3. The `is` and operator uses the following names:
+///
+/// $is<NAME>
+/// $as<NAME>
+///
+/// For local variables, the [Namer] only provides *proposed names*. These names
+/// must be disambiguated elsewhere.
class Namer {
static const List<String> javaScriptKeywords = const <String>[
// ES5 7.6.1.1 Keywords.
@@ -616,10 +614,8 @@
String get isolatePropertiesName => r'$isolateProperties';
jsAst.Name get noSuchMethodName => invocationName(Selectors.noSuchMethod_);
- /**
- * Some closures must contain their name. The name is stored in
- * [STATIC_CLOSURE_NAME_NAME].
- */
+ /// Some closures must contain their name. The name is stored in
+ /// [STATIC_CLOSURE_NAME_NAME].
String get STATIC_CLOSURE_NAME_NAME => r'$name';
String get closureInvocationSelectorName => Identifiers.call;
bool get shouldMinify => false;
@@ -763,17 +759,15 @@
return 'c\$${target.nestingLevel}';
}
- /**
- * If the [originalName] is not private returns [originalName]. Otherwise
- * mangles the [originalName] so that each library has its own distinguished
- * version of the name.
- *
- * Although the name is not guaranteed to be unique within any namespace,
- * clashes are very unlikely in practice. Therefore, it can be used in cases
- * where uniqueness is nice but not a strict requirement.
- *
- * The resulting name is a *proposed name* and is never minified.
- */
+ /// If the [originalName] is not private returns [originalName]. Otherwise
+ /// mangles the [originalName] so that each library has its own distinguished
+ /// version of the name.
+ ///
+ /// Although the name is not guaranteed to be unique within any namespace,
+ /// clashes are very unlikely in practice. Therefore, it can be used in cases
+ /// where uniqueness is nice but not a strict requirement.
+ ///
+ /// The resulting name is a *proposed name* and is never minified.
String privateName(Name originalName) {
String text = originalName.text;
@@ -933,26 +927,20 @@
CURRENT_ELEMENT_SPANNABLE, 'Unexpected special selector: $selector');
}
- /**
- * Returns the internal name used for an invocation mirror of this selector.
- */
+ /// Returns the internal name used for an invocation mirror of this selector.
jsAst.Name invocationMirrorInternalName(Selector selector) =>
invocationName(selector);
- /**
- * Returns the disambiguated name for the given field, used for constructing
- * the getter and setter names.
- */
+ /// Returns the disambiguated name for the given field, used for constructing
+ /// the getter and setter names.
jsAst.Name fieldAccessorName(FieldEntity element) {
return element.isInstanceMember
? _disambiguateMember(element.memberName)
: _disambiguateGlobalMember(element);
}
- /**
- * Returns name of the JavaScript property used to store a static or instance
- * field.
- */
+ /// Returns name of the JavaScript property used to store a static or instance
+ /// field.
jsAst.Name fieldPropertyName(FieldEntity element) {
return element.isInstanceMember
? instanceFieldPropertyName(element)
@@ -983,9 +971,7 @@
jsAst.Name globalPropertyNameForType(Entity element) =>
_disambiguateGlobalType(element);
- /**
- * Returns the JavaScript property name used to store an instance field.
- */
+ /// Returns the JavaScript property name used to store an instance field.
jsAst.Name instanceFieldPropertyName(FieldEntity element) {
ClassEntity enclosingClass = element.enclosingClass;
@@ -1410,10 +1396,8 @@
}
}
- /**
- * Returns a proposed name for the given [LibraryElement].
- * The returned id is guaranteed to be a valid JavaScript identifier.
- */
+ /// Returns a proposed name for the given [LibraryElement].
+ /// The returned id is guaranteed to be a valid JavaScript identifier.
// TODO(sra): Pre-process libraries to assign [libraryLongNames] in a way that
// is independent of the order of calls to namer.
String _proposeNameForLibrary(LibraryEntity library) {
@@ -1837,21 +1821,19 @@
}
}
-/**
- * Generator of names for [ConstantValue] values.
- *
- * The names are stable under perturbations of the source. The name is either a
- * short sequence of words, if this can be found from the constant, or a type
- * followed by a hash tag.
- *
- * List_imX // A List, with hash tag.
- * C_Sentinel // const Sentinel(), "C_" added to avoid clash
- * // with class name.
- * JSInt_methods // an interceptor.
- * Duration_16000 // const Duration(milliseconds: 16)
- * EventKeyProvider_keyup // const EventKeyProvider('keyup')
- *
- */
+/// Generator of names for [ConstantValue] values.
+///
+/// The names are stable under perturbations of the source. The name is either
+/// a short sequence of words, if this can be found from the constant, or a type
+/// followed by a hash tag.
+///
+/// List_imX // A List, with hash tag.
+/// C_Sentinel // const Sentinel(), "C_" added to avoid clash
+/// // with class name.
+/// JSInt_methods // an interceptor.
+/// Duration_16000 // const Duration(milliseconds: 16)
+/// EventKeyProvider_keyup // const EventKeyProvider('keyup')
+///
class ConstantNamingVisitor implements ConstantValueVisitor {
static final RegExp IDENTIFIER = new RegExp(r'^[A-Za-z_$][A-Za-z0-9_$]*$');
static const MAX_FRAGMENTS = 5;
@@ -2083,14 +2065,12 @@
}
}
-/**
- * Generates canonical hash values for [ConstantValue]s.
- *
- * Unfortunately, [Constant.hashCode] is not stable under minor perturbations,
- * so it can't be used for generating names. This hasher keeps consistency
- * between runs by basing hash values of the names of elements, rather than
- * their hashCodes.
- */
+/// Generates canonical hash values for [ConstantValue]s.
+///
+/// Unfortunately, [Constant.hashCode] is not stable under minor perturbations,
+/// so it can't be used for generating names. This hasher keeps consistency
+/// between runs by basing hash values of the names of elements, rather than
+/// their hashCodes.
class ConstantCanonicalHasher implements ConstantValueVisitor<int, Null> {
static const _MASK = 0x1fffffff;
static const _UINT32_LIMIT = 4 * 1024 * 1024 * 1024;
@@ -2260,12 +2240,10 @@
}
}
- /**
- * [_combine] and [_finish] are parts of the [Jenkins hash function][1],
- * modified by using masking to keep values in SMI range.
- *
- * [1]: http://en.wikipedia.org/wiki/Jenkins_hash_function
- */
+ /// [_combine] and [_finish] are parts of the [Jenkins hash function][1],
+ /// modified by using masking to keep values in SMI range.
+ ///
+ /// [1]: http://en.wikipedia.org/wiki/Jenkins_hash_function
static int _combine(int hash, int value) {
hash = _MASK & (hash + value);
hash = _MASK & (hash + (((_MASK >> 10) & hash) << 10));
diff --git a/pkg/compiler/lib/src/js_backend/runtime_types.dart b/pkg/compiler/lib/src/js_backend/runtime_types.dart
index 391393b..ec375e0 100644
--- a/pkg/compiler/lib/src/js_backend/runtime_types.dart
+++ b/pkg/compiler/lib/src/js_backend/runtime_types.dart
@@ -704,15 +704,13 @@
_RuntimeTypesBase(this._types);
- /**
- * Compute type arguments of classes that use one of their type variables in
- * is-checks and add the is-checks that they imply.
- *
- * This function must be called after all is-checks have been registered.
- *
- * TODO(karlklose): move these computations into a function producing an
- * immutable datastructure.
- */
+ /// Compute type arguments of classes that use one of their type variables in
+ /// is-checks and add the is-checks that they imply.
+ ///
+ /// This function must be called after all is-checks have been registered.
+ ///
+ /// TODO(karlklose): move these computations into a function producing an
+ /// immutable datastructure.
void registerImplicitChecks(
Set<InterfaceType> instantiatedTypes,
Iterable<ClassEntity> classesUsingChecks,
@@ -2277,20 +2275,18 @@
}
}
- /**
- * Compute a JavaScript expression that describes the necessary substitution
- * for type arguments in a subtype test.
- *
- * The result 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.
- */
+ /// Compute a JavaScript expression that describes the necessary substitution
+ /// for type arguments in a subtype test.
+ ///
+ /// The result 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.
@override
jsAst.Expression getSubstitutionCode(
Emitter emitter, Substitution substitution) {
@@ -2382,10 +2378,8 @@
TypeRepresentationGenerator(this.namer, this._nativeData);
- /**
- * Creates a type representation for [type]. [onVariable] is called to provide
- * the type representation for type variables.
- */
+ /// Creates a type representation for [type]. [onVariable] is called to
+ /// provide the type representation for type variables.
jsAst.Expression getTypeRepresentation(
Emitter emitter,
DartType type,
@@ -2788,10 +2782,8 @@
'parameters=$parameters,length=$length)';
}
-/**
- * A pair of a class that we need a check against and the type argument
- * substitution for this check.
- */
+/// A pair of a class that we need a check against and the type argument
+/// substitution for this check.
class TypeCheck {
final ClassEntity cls;
final bool needsIs;
diff --git a/pkg/compiler/lib/src/js_emitter/class_stub_generator.dart b/pkg/compiler/lib/src/js_emitter/class_stub_generator.dart
index 73a5d1c..fb31e92 100644
--- a/pkg/compiler/lib/src/js_emitter/class_stub_generator.dart
+++ b/pkg/compiler/lib/src/js_emitter/class_stub_generator.dart
@@ -85,11 +85,9 @@
'function(#, v) { return #.# = v; }', [args, receiver, fieldName]);
}
- /**
- * Documentation wanted -- johnniwinther
- *
- * Invariant: [member] must be a declaration element.
- */
+ /// Documentation wanted -- johnniwinther
+ ///
+ /// Invariant: [member] must be a declaration element.
Map<jsAst.Name, jsAst.Expression> generateCallStubsForGetter(
MemberEntity member, Map<Selector, SelectorConstraints> selectors) {
// If the method is intercepted, the stub gets the
@@ -245,12 +243,13 @@
///
/// `tearOff` takes the following arguments:
/// * `funcs`: a list of functions. These are the functions representing the
-/// member that is torn off. There can be more than one, since a member
-/// can have several stubs.
-/// Each function must have the `$callName` property set.
-/// * `applyTrampolineIndex` is the index of the stub to be used for Function.apply
+/// member that is torn off. There can be more than one, since a member
+/// can have several stubs.
+/// Each function must have the `$callName` property set.
+/// * `applyTrampolineIndex` is the index of the stub to be used for
+/// Function.apply
/// * `reflectionInfo`: contains reflective information, and the function
-/// type. TODO(floitsch): point to where this is specified.
+/// type. TODO(floitsch): point to where this is specified.
/// * `isStatic`.
/// * `name`.
/// * `isIntercepted.
diff --git a/pkg/compiler/lib/src/js_emitter/code_emitter_task.dart b/pkg/compiler/lib/src/js_emitter/code_emitter_task.dart
index e634e21..7fac11d 100644
--- a/pkg/compiler/lib/src/js_emitter/code_emitter_task.dart
+++ b/pkg/compiler/lib/src/js_emitter/code_emitter_task.dart
@@ -26,12 +26,10 @@
import 'type_test_registry.dart' show TypeTestRegistry;
import 'sorter.dart';
-/**
- * Generates the code for all used classes in the program. Static fields (even
- * in classes) are ignored, since they can be treated as non-class elements.
- *
- * The code for the containing (used) methods must exist in the `universe`.
- */
+/// Generates the code for all used classes in the program. Static fields (even
+/// in classes) are ignored, since they can be treated as non-class elements.
+///
+/// The code for the containing (used) methods must exist in the `universe`.
class CodeEmitterTask extends CompilerTask {
TypeTestRegistry typeTestRegistry;
NativeEmitter _nativeEmitter;
diff --git a/pkg/compiler/lib/src/js_emitter/interceptor_stub_generator.dart b/pkg/compiler/lib/src/js_emitter/interceptor_stub_generator.dart
index d91972f..3bbdcfa0 100644
--- a/pkg/compiler/lib/src/js_emitter/interceptor_stub_generator.dart
+++ b/pkg/compiler/lib/src/js_emitter/interceptor_stub_generator.dart
@@ -58,10 +58,8 @@
return _emitterTask.interceptorPrototypeAccess(cls);
}
- /**
- * Build a JavaScript AST node for doing a type check on
- * [cls]. [cls] must be a non-native interceptor class.
- */
+ /// Build a JavaScript AST node for doing a type check on
+ /// [cls]. [cls] must be a non-native interceptor class.
jsAst.Statement buildInterceptorCheck(ClassEntity cls) {
jsAst.Expression condition;
assert(_interceptorData.isInterceptedClass(cls));
diff --git a/pkg/compiler/lib/src/js_emitter/model.dart b/pkg/compiler/lib/src/js_emitter/model.dart
index 933f41c..7829d79 100644
--- a/pkg/compiler/lib/src/js_emitter/model.dart
+++ b/pkg/compiler/lib/src/js_emitter/model.dart
@@ -72,10 +72,8 @@
Fragment get mainFragment => fragments.first;
}
-/**
- * This class represents a JavaScript object that contains static state, like
- * classes or functions.
- */
+/// This class represents a JavaScript object that contains static state, like
+/// classes or functions.
class Holder {
final String name;
final int index;
@@ -90,12 +88,10 @@
}
}
-/**
- * This class represents one output file.
- *
- * If no library is deferred, there is only one [Fragment] of type
- * [MainFragment].
- */
+/// This class represents one output file.
+///
+/// If no library is deferred, there is only one [Fragment] of type
+/// [MainFragment].
abstract class Fragment {
/// The outputUnit should only be used during the transition to the new model.
/// Uses indicate missing information in the model.
@@ -122,12 +118,10 @@
bool get isMainFragment;
}
-/**
- * The main output file.
- *
- * This code emitted from this [Fragment] must be loaded first. It can then load
- * other [DeferredFragment]s.
- */
+/// The main output file.
+///
+/// This code emitted from this [Fragment] must be loaded first. It can then load
+/// other [DeferredFragment]s.
class MainFragment extends Fragment {
final js.Statement invokeMain;
@@ -149,9 +143,7 @@
}
}
-/**
- * An output (file) for deferred code.
- */
+/// An output (file) for deferred code.
class DeferredFragment extends Fragment {
final String name;
diff --git a/pkg/compiler/lib/src/js_emitter/native_emitter.dart b/pkg/compiler/lib/src/js_emitter/native_emitter.dart
index 85230aa..2e0dca3 100644
--- a/pkg/compiler/lib/src/js_emitter/native_emitter.dart
+++ b/pkg/compiler/lib/src/js_emitter/native_emitter.dart
@@ -46,36 +46,35 @@
NativeData get _nativeData => _closedWorld.nativeData;
InterceptorData get _interceptorData => _closedWorld.interceptorData;
- /**
- * Prepares native classes for emission. Returns the unneeded classes.
- *
- * Removes trivial classes (that can be represented by a super type) and
- * generates properties that have to be added to classes (native or not).
- *
- * Updates the `nativeLeafTags`, `nativeNonLeafTags` and `nativeExtensions`
- * fields of the given classes. This data must be emitted with the
- * corresponding classes.
- *
- * The interceptors are filtered to avoid emitting trivial interceptors. For
- * example, if the program contains no code that can distinguish between the
- * numerous subclasses of `Element` then we can pretend that `Element` is a
- * leaf class, and all instances of subclasses of `Element` are instances of
- * `Element`.
- *
- * There is also a performance benefit (in addition to the obvious code size
- * benefit), due to how [getNativeInterceptor] works. Finding the interceptor
- * of a leaf class in the hierarchy is more efficient that a non-leaf, so it
- * improves performance when more classes can be treated as leaves.
- *
- * [classes] contains native classes, mixin applications, and user subclasses
- * of native classes.
- *
- * [interceptorClassesNeededByConstants] contains the interceptors that are
- * referenced by constants.
- *
- * [classesModifiedByEmitRTISupport] contains the list of classes that must
- * exist, because runtime-type support adds information to the class.
- */
+ /// Prepares native classes for emission. Returns the unneeded classes.
+ ///
+ /// Removes trivial classes (that can be represented by a super type) and
+ /// generates properties that have to be added to classes (native or not).
+ ///
+ /// Updates the `nativeLeafTags`, `nativeNonLeafTags` and `nativeExtensions`
+ /// fields of the given classes. This data must be emitted with the
+ /// corresponding classes.
+ ///
+ /// The interceptors are filtered to avoid emitting trivial interceptors. For
+ /// example, if the program contains no code that can distinguish between the
+ /// numerous subclasses of `Element` then we can pretend that `Element` is a
+ /// leaf class, and all instances of subclasses of `Element` are instances of
+ /// `Element`.
+ ///
+ /// There is also a performance benefit (in addition to the obvious code size
+ /// benefit), due to how [getNativeInterceptor] works. Finding the
+ /// interceptor of a leaf class in the hierarchy is more efficient that a
+ /// non-leaf, so it improves performance when more classes can be treated as
+ /// leaves.
+ ///
+ /// [classes] contains native classes, mixin applications, and user subclasses
+ /// of native classes.
+ ///
+ /// [interceptorClassesNeededByConstants] contains the interceptors that are
+ /// referenced by constants.
+ ///
+ /// [classesModifiedByEmitRTISupport] contains the list of classes that must
+ /// exist, because runtime-type support adds information to the class.
Set<Class> prepareNativeClasses(
List<Class> classes,
Set<ClassEntity> interceptorClassesNeededByConstants,
@@ -219,11 +218,9 @@
.toSet();
}
- /**
- * Computes the native classes that are extended (subclassed) by non-native
- * classes and the set non-mative classes that extend them. (A List is used
- * instead of a Set for out stability).
- */
+ /// Computes the native classes that are extended (subclassed) by non-native
+ /// classes and the set non-mative classes that extend them. (A List is used
+ /// instead of a Set for out stability).
Map<Class, List<Class>> computeExtensionPoints(List<Class> classes) {
Class nativeSuperclassOf(Class cls) {
if (cls == null) return null;
diff --git a/pkg/compiler/lib/src/js_emitter/program_builder/collector.dart b/pkg/compiler/lib/src/js_emitter/program_builder/collector.dart
index 6592f68..e57a3ab 100644
--- a/pkg/compiler/lib/src/js_emitter/program_builder/collector.dart
+++ b/pkg/compiler/lib/src/js_emitter/program_builder/collector.dart
@@ -4,12 +4,10 @@
part of dart2js.js_emitter.program_builder;
-/**
- * Generates the code for all used classes in the program. Static fields (even
- * in classes) are ignored, since they can be treated as non-class elements.
- *
- * The code for the containing (used) methods must exist in the `universe`.
- */
+/// Generates the code for all used classes in the program. Static fields (even
+/// in classes) are ignored, since they can be treated as non-class elements.
+///
+/// The code for the containing (used) methods must exist in the `universe`.
class Collector {
final CompilerOptions _options;
final JCommonElements _commonElements;
@@ -78,10 +76,8 @@
return classes;
}
- /**
- * Return a function that returns true if its argument is a class
- * that needs to be emitted.
- */
+ /// Return a function that returns true if its argument is a class
+ /// that needs to be emitted.
Function computeClassFilter(Iterable<ClassEntity> backendTypeHelpers) {
Set<ClassEntity> unneededClasses = new Set<ClassEntity>();
// The [Bool] class is not marked as abstract, but has a factory
@@ -129,9 +125,7 @@
];
}
- /**
- * Compute all the constants that must be emitted.
- */
+ /// Compute all the constants that must be emitted.
void computeNeededConstants() {
List<ConstantValue> constants =
_worldBuilder.getConstantsForEmission(_emitter.compareConstants);
diff --git a/pkg/compiler/lib/src/js_emitter/program_builder/field_visitor.dart b/pkg/compiler/lib/src/js_emitter/program_builder/field_visitor.dart
index e1b0d46..493afa9 100644
--- a/pkg/compiler/lib/src/js_emitter/program_builder/field_visitor.dart
+++ b/pkg/compiler/lib/src/js_emitter/program_builder/field_visitor.dart
@@ -4,24 +4,22 @@
part of dart2js.js_emitter.program_builder;
-/**
- * [member] is a field (instance, static, or top level).
- *
- * [name] is the field name that the [Namer] has picked for this field's
- * storage, that is, the JavaScript property name.
- *
- * [accessorName] is the name of the accessor. For instance fields this is
- * mostly the same as [name] except when [member] is shadowing a field in its
- * superclass. For other fields, they are rarely the same.
- *
- * [needsGetter] and [needsSetter] represent if a getter or a setter
- * respectively is needed. There are many factors in this, for example, if the
- * accessor can be inlined.
- *
- * [needsCheckedSetter] indicates that a checked getter is needed, and in this
- * case, [needsSetter] is always false. [needsCheckedSetter] is only true when
- * type assertions are enabled (checked mode).
- */
+/// [member] is a field (instance, static, or top level).
+///
+/// [name] is the field name that the [Namer] has picked for this field's
+/// storage, that is, the JavaScript property name.
+///
+/// [accessorName] is the name of the accessor. For instance fields this is
+/// mostly the same as [name] except when [member] is shadowing a field in its
+/// superclass. For other fields, they are rarely the same.
+///
+/// [needsGetter] and [needsSetter] represent if a getter or a setter
+/// respectively is needed. There are many factors in this, for example, if the
+/// accessor can be inlined.
+///
+/// [needsCheckedSetter] indicates that a checked getter is needed, and in this
+/// case, [needsSetter] is always false. [needsCheckedSetter] is only true when
+/// type assertions are enabled (checked mode).
typedef void AcceptField(FieldEntity member, js.Name name, js.Name accessorName,
bool needsGetter, bool needsSetter, bool needsCheckedSetter);
@@ -43,22 +41,20 @@
this._namer,
this._closedWorld);
- /**
- * Invokes [f] for each of the fields of [element].
- *
- * [element] must be a [ClassEntity] or a [LibraryEntity].
- *
- * If [element] is a [ClassEntity], the static fields of the class are
- * visited if [visitStatics] is true and the instance fields are visited if
- * [visitStatics] is false.
- *
- * If [element] is a [LibraryEntity], [visitStatics] must be true.
- *
- * When visiting the instance fields of a class, the fields of its superclass
- * are also visited if the class is instantiated.
- *
- * Invariant: [element] must be a declaration element.
- */
+ /// Invokes [f] for each of the fields of [element].
+ ///
+ /// [element] must be a [ClassEntity] or a [LibraryEntity].
+ ///
+ /// If [element] is a [ClassEntity], the static fields of the class are
+ /// visited if [visitStatics] is true and the instance fields are visited if
+ /// [visitStatics] is false.
+ ///
+ /// If [element] is a [LibraryEntity], [visitStatics] must be true.
+ ///
+ /// When visiting the instance fields of a class, the fields of its superclass
+ /// are also visited if the class is instantiated.
+ ///
+ /// Invariant: [element] must be a declaration element.
void visitFields(AcceptField f,
{bool visitStatics: false, LibraryEntity library, ClassEntity cls}) {
bool isNativeClass = false;
diff --git a/pkg/compiler/lib/src/js_emitter/runtime_type_generator.dart b/pkg/compiler/lib/src/js_emitter/runtime_type_generator.dart
index 7d974f3..02cdf45 100644
--- a/pkg/compiler/lib/src/js_emitter/runtime_type_generator.dart
+++ b/pkg/compiler/lib/src/js_emitter/runtime_type_generator.dart
@@ -102,13 +102,11 @@
: _outputUnitVisitor = new _TypeContainedInOutputUnitVisitor(
_commonElements, _outputUnitData);
- /**
- * Generate "is tests" for [cls] itself, and the "is tests" for the
- * classes it implements and type argument substitution functions for these
- * tests. We don't need to add the "is tests" of the super class because
- * they will be inherited at runtime, but we may need to generate the
- * substitutions, because they may have changed.
- */
+ /// Generate "is tests" for [cls] itself, and the "is tests" for the
+ /// classes it implements and type argument substitution functions for these
+ /// tests. We don't need to add the "is tests" of the super class because
+ /// they will be inherited at runtime, but we may need to generate the
+ /// substitutions, because they may have changed.
/// Generates all properties necessary for is-checks on the [classElement].
///
diff --git a/pkg/compiler/lib/src/js_emitter/startup_emitter/fragment_emitter.dart b/pkg/compiler/lib/src/js_emitter/startup_emitter/fragment_emitter.dart
index e5cabfe..8e5224c 100644
--- a/pkg/compiler/lib/src/js_emitter/startup_emitter/fragment_emitter.dart
+++ b/pkg/compiler/lib/src/js_emitter/startup_emitter/fragment_emitter.dart
@@ -560,14 +560,12 @@
#inheritance;
}''';
-/**
- * This class builds a JavaScript tree for a given fragment.
- *
- * A fragment is generally written into a separate file so that it can be
- * loaded dynamically when a deferred library is loaded.
- *
- * This class is stateless and can be reused for different fragments.
- */
+/// This class builds a JavaScript tree for a given fragment.
+///
+/// A fragment is generally written into a separate file so that it can be
+/// loaded dynamically when a deferred library is loaded.
+///
+/// This class is stateless and can be reused for different fragments.
class FragmentEmitter {
final Compiler compiler;
final Namer namer;
diff --git a/pkg/compiler/lib/src/native/behavior.dart b/pkg/compiler/lib/src/native/behavior.dart
index a437151..61900e4 100644
--- a/pkg/compiler/lib/src/native/behavior.dart
+++ b/pkg/compiler/lib/src/native/behavior.dart
@@ -94,36 +94,34 @@
int get index => values.indexOf(this);
}
-/**
- * A summary of the behavior of a native element.
- *
- * Native code can return values of one type and cause native subtypes of
- * another type to be instantiated. By default, we compute both from the
- * declared type.
- *
- * A field might yield any native type that 'is' the field type.
- *
- * A method might create and return instances of native subclasses of its
- * declared return type, and a callback argument may be called with instances of
- * the callback parameter type (e.g. Event).
- *
- * If there is one or more `@Creates` annotations, the union of the named types
- * replaces the inferred instantiated type, and the return type is ignored for
- * the purpose of inferring instantiated types.
- *
- * @Creates('IDBCursor') // Created asynchronously.
- * @Creates('IDBRequest') // Created synchronously (for return value).
- * IDBRequest openCursor();
- *
- * If there is one or more `@Returns` annotations, the union of the named types
- * replaces the declared return type.
- *
- * @Returns('IDBRequest')
- * IDBRequest openCursor();
- *
- * Types in annotations are non-nullable, so include `@Returns('Null')` if
- * `null` may be returned.
- */
+/// A summary of the behavior of a native element.
+///
+/// Native code can return values of one type and cause native subtypes of
+/// another type to be instantiated. By default, we compute both from the
+/// declared type.
+///
+/// A field might yield any native type that 'is' the field type.
+///
+/// A method might create and return instances of native subclasses of its
+/// declared return type, and a callback argument may be called with instances
+/// of the callback parameter type (e.g. Event).
+///
+/// If there is one or more `@Creates` annotations, the union of the named types
+/// replaces the inferred instantiated type, and the return type is ignored for
+/// the purpose of inferring instantiated types.
+///
+/// @Creates('IDBCursor') // Created asynchronously.
+/// @Creates('IDBRequest') // Created synchronously (for return value).
+/// IDBRequest openCursor();
+///
+/// If there is one or more `@Returns` annotations, the union of the named types
+/// replaces the declared return type.
+///
+/// @Returns('IDBRequest')
+/// IDBRequest openCursor();
+///
+/// Types in annotations are non-nullable, so include `@Returns('Null')` if
+/// `null` may be returned.
class NativeBehavior {
/// Tag used for identifying serialized [NativeBehavior] objects in a
/// debugging data stream.
@@ -742,11 +740,9 @@
}
}
- /**
- * Returns a list of type constraints from the annotations of
- * [annotationClass].
- * Returns `null` if no constraints.
- */
+ /// Returns a list of type constraints from the annotations of
+ /// [annotationClass].
+ /// Returns `null` if no constraints.
List _collect(Iterable<ConstantValue> metadata, ClassEntity annotationClass,
TypeLookup lookupType) {
var types = null;
diff --git a/pkg/compiler/lib/src/native/enqueue.dart b/pkg/compiler/lib/src/native/enqueue.dart
index a3a1dd2..dfd4b8f 100644
--- a/pkg/compiler/lib/src/native/enqueue.dart
+++ b/pkg/compiler/lib/src/native/enqueue.dart
@@ -14,9 +14,8 @@
import 'behavior.dart';
import 'resolver.dart' show NativeClassFinder;
-/**
- * This could be an abstract class but we use it as a stub for the dart_backend.
- */
+/// This could be an abstract class but we use it as a stub for the
+/// dart_backend.
class NativeEnqueuer {
/// Called when a [type] has been instantiated natively.
void onInstantiatedType(InterfaceType type) {}
diff --git a/pkg/compiler/lib/src/ordered_typeset.dart b/pkg/compiler/lib/src/ordered_typeset.dart
index 57ed4cb..e3b4f3e 100644
--- a/pkg/compiler/lib/src/ordered_typeset.dart
+++ b/pkg/compiler/lib/src/ordered_typeset.dart
@@ -13,23 +13,21 @@
import 'elements/types.dart';
import 'serialization/serialization.dart';
-/**
- * An ordered set of the supertypes of a class. The supertypes of a class are
- * ordered by decreasing hierarchy depth and by the order they are extended,
- * mixed in, or implemented.
- *
- * For these classes
- *
- * class A {} // Depth = 1.
- * class B {} // Depth = 1.
- * class C extends B implements A {} // Depth 2.
- *
- * the ordered supertypes are
- *
- * A: [A, Object]
- * B: [B, Object]
- * C: [C, B, A, Object]
- */
+/// An ordered set of the supertypes of a class. The supertypes of a class are
+/// ordered by decreasing hierarchy depth and by the order they are extended,
+/// mixed in, or implemented.
+///
+/// For these classes
+///
+/// class A {} // Depth = 1.
+/// class B {} // Depth = 1.
+/// class C extends B implements A {} // Depth 2.
+///
+/// the ordered supertypes are
+///
+/// A: [A, Object]
+/// B: [B, Object]
+/// C: [C, B, A, Object]
class OrderedTypeSet {
/// Tag used for identifying serialized [OrderedTypeSet] objects in a
/// debugging data stream.
@@ -198,23 +196,21 @@
String toString() => types.toString();
}
-/**
- * Builder for creation an ordered set of the supertypes of a class. The
- * supertypes are ordered by decreasing hierarchy depth and by the order they
- * are extended, mixed in, or implemented.
- *
- * For these classes
- *
- * class A {} // Depth = 1.
- * class B {} // Depth = 1.
- * class C extends B implements A {} // Depth 2.
- *
- * the ordered supertypes are
- *
- * A: [A, Object]
- * B: [B, Object]
- * C: [C, B, A, Object]
- */
+/// Builder for creation an ordered set of the supertypes of a class. The
+/// supertypes are ordered by decreasing hierarchy depth and by the order they
+/// are extended, mixed in, or implemented.
+///
+/// For these classes
+///
+/// class A {} // Depth = 1.
+/// class B {} // Depth = 1.
+/// class C extends B implements A {} // Depth 2.
+///
+/// the ordered supertypes are
+///
+/// A: [A, Object]
+/// B: [B, Object]
+/// C: [C, B, A, Object]
abstract class OrderedTypeSetBuilder {
OrderedTypeSet createOrderedTypeSet(
InterfaceType supertype, Link<DartType> interfaces);
@@ -257,10 +253,8 @@
return toTypeSet();
}
- /**
- * Adds [type] and all supertypes of [type] to [allSupertypes] while
- * substituting type variables.
- */
+ /// Adds [type] and all supertypes of [type] to [allSupertypes] while
+ /// substituting type variables.
void _addAllSupertypes(InterfaceType type) {
ClassEntity classElement = type.element;
Link<InterfaceType> supertypes = getOrderedTypeSet(classElement).supertypes;
diff --git a/pkg/compiler/lib/src/script.dart b/pkg/compiler/lib/src/script.dart
index 403776b..5adbdae 100644
--- a/pkg/compiler/lib/src/script.dart
+++ b/pkg/compiler/lib/src/script.dart
@@ -9,18 +9,14 @@
class Script {
final SourceFile file;
- /**
- * The readable URI from which this script was loaded.
- *
- * See [LibraryLoader] for terminology on URIs.
- */
+ /// The readable URI from which this script was loaded.
+ ///
+ /// See [LibraryLoader] for terminology on URIs.
final Uri readableUri;
- /**
- * The resource URI from which this script was loaded.
- *
- * See [LibraryLoader] for terminology on URIs.
- */
+ /// The resource URI from which this script was loaded.
+ ///
+ /// See [LibraryLoader] for terminology on URIs.
final Uri resourceUri;
/// This script was synthesized.
diff --git a/pkg/compiler/lib/src/ssa/builder_kernel.dart b/pkg/compiler/lib/src/ssa/builder_kernel.dart
index 1c14b38..1674df2 100644
--- a/pkg/compiler/lib/src/ssa/builder_kernel.dart
+++ b/pkg/compiler/lib/src/ssa/builder_kernel.dart
@@ -4933,10 +4933,8 @@
..cleanUp();
}
- /**
- * Try to inline [element] within the correct context of the builder. The
- * insertion point is the state of the builder.
- */
+ /// Try to inline [element] within the correct context of the builder. The
+ /// insertion point is the state of the builder.
bool _tryInlineMethod(
FunctionEntity function,
Selector selector,
diff --git a/pkg/compiler/lib/src/ssa/codegen.dart b/pkg/compiler/lib/src/ssa/codegen.dart
index ea0e94a..dc941f4 100644
--- a/pkg/compiler/lib/src/ssa/codegen.dart
+++ b/pkg/compiler/lib/src/ssa/codegen.dart
@@ -134,26 +134,22 @@
}
class SsaCodeGenerator implements HVisitor, HBlockInformationVisitor {
- /**
- * Returned by [expressionType] to tell how code can be generated for
- * a subgraph.
- * - [TYPE_STATEMENT] means that the graph must be generated as a statement,
- * which is always possible.
- * - [TYPE_EXPRESSION] means that the graph can be generated as an expression,
- * or possibly several comma-separated expressions.
- * - [TYPE_DECLARATION] means that the graph can be generated as an
- * expression, and that it only generates expressions of the form
- * variable = expression
- * which are also valid as parts of a "var" declaration.
- */
+ /// Returned by [expressionType] to tell how code can be generated for
+ /// a subgraph.
+ /// - [TYPE_STATEMENT] means that the graph must be generated as a statement,
+ /// which is always possible.
+ /// - [TYPE_EXPRESSION] means that the graph can be generated as an expression,
+ /// or possibly several comma-separated expressions.
+ /// - [TYPE_DECLARATION] means that the graph can be generated as an
+ /// expression, and that it only generates expressions of the form
+ /// variable = expression
+ /// which are also valid as parts of a "var" declaration.
static const int TYPE_STATEMENT = 0;
static const int TYPE_EXPRESSION = 1;
static const int TYPE_DECLARATION = 2;
- /**
- * Whether we are currently generating expressions instead of statements.
- * This includes declarations, which are generated as expressions.
- */
+ /// Whether we are currently generating expressions instead of statements.
+ /// This includes declarations, which are generated as expressions.
bool isGeneratingExpression = false;
final CompilerOptions _options;
@@ -180,10 +176,8 @@
List<js.Expression> expressionStack;
List<js.Block> oldContainerStack;
- /**
- * Contains the names of the instructions, as well as the parallel
- * copies to perform on block transitioning.
- */
+ /// Contains the names of the instructions, as well as the parallel
+ /// copies to perform on block transitioning.
VariableNames variableNames;
/// `true` when we need to generate a `var` declaration at function entry,
@@ -191,17 +185,13 @@
/// middle of the function.
bool shouldGroupVarDeclarations = false;
- /**
- * While generating expressions, we can't insert variable declarations.
- * Instead we declare them at the start of the function. When minifying
- * we do this most of the time, because it reduces the size unless there
- * is only one variable.
- */
+ /// While generating expressions, we can't insert variable declarations.
+ /// Instead we declare them at the start of the function. When minifying
+ /// we do this most of the time, because it reduces the size unless there
+ /// is only one variable.
final Set<String> collectedVariableDeclarations;
- /**
- * Set of variables and parameters that have already been declared.
- */
+ /// Set of variables and parameters that have already been declared.
final Set<String> declaredLocals;
HGraph currentGraph;
@@ -332,10 +322,8 @@
return hasNonBitOpUser(instruction, new Set<HPhi>());
}
- /**
- * If the [instruction] is not `null` it will be used to attach the position
- * to the [statement].
- */
+ /// If the [instruction] is not `null` it will be used to attach the position
+ /// to the [statement].
void pushStatement(js.Statement statement) {
assert(expressionStack.isEmpty);
currentContainer.statements.add(statement);
@@ -345,20 +333,16 @@
currentContainer.statements.insert(0, statement);
}
- /**
- * If the [instruction] is not `null` it will be used to attach the position
- * to the [expression].
- */
+ /// If the [instruction] is not `null` it will be used to attach the position
+ /// to the [expression].
pushExpressionAsStatement(
js.Expression expression, SourceInformation sourceInformation) {
pushStatement(new js.ExpressionStatement(expression)
.withSourceInformation(sourceInformation));
}
- /**
- * If the [instruction] is not `null` it will be used to attach the position
- * to the [expression].
- */
+ /// If the [instruction] is not `null` it will be used to attach the position
+ /// to the [expression].
push(js.Expression expression) {
expressionStack.add(expression);
}
@@ -507,15 +491,13 @@
subGraph = oldSubGraph;
}
- /**
- * Check whether a sub-graph can be generated as an expression, or even
- * as a declaration, or if it has to fall back to being generated as
- * a statement.
- * Expressions are anything that doesn't generate control flow constructs.
- * Declarations must only generate assignments on the form "id = expression",
- * and not, e.g., expressions where the value isn't assigned, or where it's
- * assigned to something that's not a simple variable.
- */
+ /// Check whether a sub-graph can be generated as an expression, or even
+ /// as a declaration, or if it has to fall back to being generated as
+ /// a statement.
+ /// Expressions are anything that doesn't generate control flow constructs.
+ /// Declarations must only generate assignments on the form "id = expression",
+ /// and not, e.g., expressions where the value isn't assigned, or where it's
+ /// assigned to something that's not a simple variable.
int expressionType(HExpressionInformation info) {
// The only HExpressionInformation used as part of a HBlockInformation is
// current HSubExpressionBlockInformation, so it's the only one reaching
@@ -580,12 +562,10 @@
(limits.end.last is HConditionalBranch);
}
- /**
- * Generate statements from block information.
- * If the block information contains expressions, generate only
- * assignments, and if it ends in a conditional branch, don't generate
- * the condition.
- */
+ /// Generate statements from block information.
+ /// If the block information contains expressions, generate only
+ /// assignments, and if it ends in a conditional branch, don't generate
+ /// the condition.
void generateStatements(HBlockInformation block) {
if (block is HStatementInformation) {
block.accept(this);
@@ -604,12 +584,10 @@
return result;
}
- /**
- * If the [block] only contains one statement returns that statement. If the
- * that statement itself is a block, recursively calls this method.
- *
- * If the block is empty, returns a new instance of [js.NOP].
- */
+ /// If the [block] only contains one statement returns that statement. If the
+ /// that statement itself is a block, recursively calls this method.
+ ///
+ /// If the block is empty, returns a new instance of [js.NOP].
js.Statement unwrapStatement(js.Block block) {
int len = block.statements.length;
if (len == 0) return new js.EmptyStatement();
@@ -621,9 +599,7 @@
return block;
}
- /**
- * Generate expressions from block information.
- */
+ /// Generate expressions from block information.
js.Expression generateExpression(HExpressionInformation expression) {
// Currently we only handle sub-expression graphs.
assert(expression is HSubExpressionBlockInformation);
@@ -651,9 +627,7 @@
}
}
- /**
- * Only visits the arguments starting at inputs[HInvoke.ARGUMENTS_OFFSET].
- */
+ /// Only visits the arguments starting at inputs[HInvoke.ARGUMENTS_OFFSET].
List<js.Expression> visitArguments(List<HInstruction> inputs,
{int start: HInvoke.ARGUMENTS_OFFSET}) {
assert(inputs.length >= start);
@@ -1331,10 +1305,8 @@
assignVariable(destination, new js.VariableUse(source), sourceInformation);
}
- /**
- * Sequentialize a list of conceptually parallel copies. Parallel
- * copies may contain cycles, that this method breaks.
- */
+ /// Sequentialize a list of conceptually parallel copies. Parallel
+ /// copies may contain cycles, that this method breaks.
void sequentializeCopies(
Iterable<Copy<HInstruction>> instructionCopies,
String tempName,
diff --git a/pkg/compiler/lib/src/ssa/codegen_helpers.dart b/pkg/compiler/lib/src/ssa/codegen_helpers.dart
index 2fc43bb..78ddc04 100644
--- a/pkg/compiler/lib/src/ssa/codegen_helpers.dart
+++ b/pkg/compiler/lib/src/ssa/codegen_helpers.dart
@@ -12,10 +12,8 @@
import '../world.dart' show JClosedWorld;
import 'nodes.dart';
-/**
- * Replaces some instructions with specialized versions to make codegen easier.
- * Caches codegen information on nodes.
- */
+/// Replaces some instructions with specialized versions to make codegen easier.
+/// Caches codegen information on nodes.
class SsaInstructionSelection extends HBaseVisitor {
final JClosedWorld _closedWorld;
final InterceptorData _interceptorData;
@@ -341,10 +339,8 @@
}
}
-/**
- * Remove [HTypeKnown] instructions from the graph, to make codegen
- * analysis easier.
- */
+/// Remove [HTypeKnown] instructions from the graph, to make codegen
+/// analysis easier.
class SsaTypeKnownRemover extends HBaseVisitor {
void visitGraph(HGraph graph) {
visitDominatorTree(graph);
@@ -370,10 +366,8 @@
}
}
-/**
- * Remove [HTypeConversion] instructions from the graph in '--trust-primitives'
- * mode.
- */
+/// Remove [HTypeConversion] instructions from the graph in '--trust-primitives'
+/// mode.
class SsaTrustedCheckRemover extends HBaseVisitor {
final CompilerOptions _options;
@@ -401,29 +395,25 @@
}
}
-/**
- * Instead of emitting each SSA instruction with a temporary variable
- * mark instructions that can be emitted at their use-site.
- * For example, in:
- * t0 = 4;
- * t1 = 3;
- * t2 = add(t0, t1);
- * t0 and t1 would be marked and the resulting code would then be:
- * t2 = add(4, 3);
- */
+/// Instead of emitting each SSA instruction with a temporary variable
+/// mark instructions that can be emitted at their use-site.
+/// For example, in:
+/// t0 = 4;
+/// t1 = 3;
+/// t2 = add(t0, t1);
+/// t0 and t1 would be marked and the resulting code would then be:
+/// t2 = add(4, 3);
class SsaInstructionMerger extends HBaseVisitor {
final AbstractValueDomain _abstractValueDomain;
final SuperMemberData _superMemberData;
- /**
- * List of [HInstruction] that the instruction merger expects in
- * order when visiting the inputs of an instruction.
- */
+
+ /// List of [HInstruction] that the instruction merger expects in
+ /// order when visiting the inputs of an instruction.
List<HInstruction> expectedInputs;
- /**
- * Set of pure [HInstruction] that the instruction merger expects to
- * find. The order of pure instructions do not matter, as they will
- * not be affected by side effects.
- */
+
+ /// Set of pure [HInstruction] that the instruction merger expects to
+ /// find. The order of pure instructions do not matter, as they will
+ /// not be affected by side effects.
Set<HInstruction> pureInputs;
Set<HInstruction> generateAtUseSite;
@@ -710,11 +700,9 @@
}
}
-/**
- * Detect control flow arising from short-circuit logical and
- * conditional operators, and prepare the program to be generated
- * using these operators instead of nested ifs and boolean variables.
- */
+/// Detect control flow arising from short-circuit logical and
+/// conditional operators, and prepare the program to be generated
+/// using these operators instead of nested ifs and boolean variables.
class SsaConditionMerger extends HGraphVisitor {
Set<HInstruction> generateAtUseSite;
Set<HInstruction> controlFlowOperators;
@@ -730,10 +718,8 @@
visitPostDominatorTree(graph);
}
- /**
- * Check if a block has at least one statement other than
- * [instruction].
- */
+ /// Check if a block has at least one statement other than
+ /// [instruction].
bool hasAnyStatement(HBasicBlock block, HInstruction instruction) {
// If [instruction] is not in [block], then if the block is not
// empty, we know there will be a statement to emit.
diff --git a/pkg/compiler/lib/src/ssa/interceptor_simplifier.dart b/pkg/compiler/lib/src/ssa/interceptor_simplifier.dart
index 0ea8717..3f5d89b 100644
--- a/pkg/compiler/lib/src/ssa/interceptor_simplifier.dart
+++ b/pkg/compiler/lib/src/ssa/interceptor_simplifier.dart
@@ -12,26 +12,24 @@
import 'nodes.dart';
import 'optimize.dart';
-/**
- * This phase simplifies interceptors in multiple ways:
- *
- * 1) If the interceptor is for an object whose type is known, it
- * tries to use a constant interceptor instead.
- *
- * 2) Interceptors are specialized based on the selector it is used with.
- *
- * 3) If we know the object is not intercepted, we just use the object
- * instead.
- *
- * 4) Single use interceptors at dynamic invoke sites are replaced with 'one
- * shot interceptors' which are synthesized static helper functions that fetch
- * the interceptor and then call the method. This saves code size and makes the
- * receiver of an intercepted call a candidate for being generated at use site.
- *
- * 5) Some HIs operations on an interceptor are replaced with a HIs version that
- * uses 'instanceof' rather than testing a type flag.
- *
- */
+/// This phase simplifies interceptors in multiple ways:
+///
+/// 1) If the interceptor is for an object whose type is known, it
+/// tries to use a constant interceptor instead.
+///
+/// 2) Interceptors are specialized based on the selector it is used with.
+///
+/// 3) If we know the object is not intercepted, we just use the object
+/// instead.
+///
+/// 4) Single use interceptors at dynamic invoke sites are replaced with 'one
+/// shot interceptors' which are synthesized static helper functions that fetch
+/// the interceptor and then call the method. This saves code size and makes the
+/// receiver of an intercepted call a candidate for being generated at use site.
+///
+/// 5) Some HIs operations on an interceptor are replaced with a HIs version that
+/// uses 'instanceof' rather than testing a type flag.
+///
class SsaSimplifyInterceptors extends HBaseVisitor
implements OptimizationPhase {
final String name = "SsaSimplifyInterceptors";
diff --git a/pkg/compiler/lib/src/ssa/invoke_dynamic_specializers.dart b/pkg/compiler/lib/src/ssa/invoke_dynamic_specializers.dart
index 847ad4e..18f2ce2 100644
--- a/pkg/compiler/lib/src/ssa/invoke_dynamic_specializers.dart
+++ b/pkg/compiler/lib/src/ssa/invoke_dynamic_specializers.dart
@@ -16,12 +16,10 @@
import 'nodes.dart';
import 'types.dart';
-/**
- * [InvokeDynamicSpecializer] and its subclasses are helpers to
- * optimize intercepted dynamic calls. It knows what input types
- * would be beneficial for performance, and how to change a invoke
- * dynamic to a builtin instruction (e.g. HIndex, HBitNot).
- */
+/// [InvokeDynamicSpecializer] and its subclasses are helpers to
+/// optimize intercepted dynamic calls. It knows what input types
+/// would be beneficial for performance, and how to change a invoke
+/// dynamic to a builtin instruction (e.g. HIndex, HBitNot).
class InvokeDynamicSpecializer {
const InvokeDynamicSpecializer();
diff --git a/pkg/compiler/lib/src/ssa/nodes.dart b/pkg/compiler/lib/src/ssa/nodes.dart
index 568ae0b..dc693ef 100644
--- a/pkg/compiler/lib/src/ssa/nodes.dart
+++ b/pkg/compiler/lib/src/ssa/nodes.dart
@@ -510,7 +510,7 @@
class SubExpression extends SubGraph {
const SubExpression(HBasicBlock start, HBasicBlock end) : super(start, end);
- /** Find the condition expression if this sub-expression is a condition. */
+ /// Find the condition expression if this sub-expression is a condition.
HInstruction get conditionExpression {
HInstruction last = end.last;
if (last is HConditionalBranch || last is HSwitch) return last.inputs[0];
@@ -580,7 +580,7 @@
detach(instruction);
}
- /** Linear search for [instruction]. */
+ /// Linear search for [instruction].
bool contains(HInstruction instruction) {
HInstruction cursor = first;
while (cursor != null) {
@@ -760,10 +760,8 @@
}
}
- /**
- * Rewrites all uses of the [from] instruction to using the [to]
- * instruction instead.
- */
+ /// Rewrites all uses of the [from] instruction to using the [to]
+ /// instruction instead.
void rewrite(HInstruction from, HInstruction to) {
for (HInstruction use in from.usedBy) {
use.rewriteInput(from, to);
@@ -772,11 +770,9 @@
from.usedBy.clear();
}
- /**
- * Rewrites all uses of the [from] instruction to using either the
- * [to] instruction, or a [HCheck] instruction that has better type
- * information on [to], and that dominates the user.
- */
+ /// Rewrites all uses of the [from] instruction to using either the
+ /// [to] instruction, or a [HCheck] instruction that has better type
+ /// information on [to], and that dominates the user.
void rewriteWithBetterUser(HInstruction from, HInstruction to) {
// BUG(11841): Turn this method into a phase to be run after GVN phases.
Link<HCheck> better = const Link<HCheck>();
@@ -992,11 +988,9 @@
bool get isMovable => useGvn();
- /**
- * A pure instruction is an instruction that does not have any side
- * effect, nor any dependency. They can be moved anywhere in the
- * graph.
- */
+ /// A pure instruction is an instruction that does not have any side
+ /// effect, nor any dependency. They can be moved anywhere in the
+ /// graph.
bool isPure(AbstractValueDomain domain) {
return !sideEffects.hasSideEffects() &&
!sideEffects.dependsOnSomething() &&
@@ -1105,9 +1099,7 @@
AbstractBool isPrimitiveOrNull(AbstractValueDomain domain) =>
domain.isPrimitiveOrNull(instructionType);
- /**
- * Type of the instruction.
- */
+ /// Type of the instruction.
AbstractValue instructionType;
Selector get selector => null;
@@ -1185,7 +1177,7 @@
}
}
- /** Removes all occurrences of [instruction] from [list]. */
+ /// Removes all occurrences of [instruction] from [list].
void removeFromList(List<HInstruction> list, HInstruction instruction) {
int length = list.length;
int i = 0;
@@ -1200,7 +1192,7 @@
list.length = length;
}
- /** Removes all occurrences of [user] from [usedBy]. */
+ /// Removes all occurrences of [user] from [usedBy].
void removeUser(HInstruction user) {
removeFromList(usedBy, user);
}
@@ -1299,10 +1291,8 @@
}
}
- /**
- * Return whether the instructions do not belong to a loop or
- * belong to the same loop.
- */
+ /// Return whether the instructions do not belong to a loop or
+ /// belong to the same loop.
bool hasSameLoopHeaderAs(HInstruction other) {
return block.enclosingLoopHeader == other.block.enclosingLoopHeader;
}
@@ -1466,10 +1456,8 @@
String toString() => 'HRef(${value})';
}
-/**
- * Late instructions are used after the main optimization phases. They capture
- * codegen decisions just prior to generating JavaScript.
- */
+/// Late instructions are used after the main optimization phases. They capture
+/// codegen decisions just prior to generating JavaScript.
abstract class HLateInstruction extends HInstruction {
HLateInstruction(List<HInstruction> inputs, AbstractValue type)
: super(inputs, type);
@@ -1488,13 +1476,11 @@
bool dataEquals(HInstruction other) => true;
}
-/**
- * A [HCheck] instruction is an instruction that might do a dynamic
- * check at runtime on another instruction. To have proper instruction
- * dependencies in the graph, instructions that depend on the check
- * being done reference the [HCheck] instruction instead of the
- * instruction itself.
- */
+/// A [HCheck] instruction is an instruction that might do a dynamic
+/// check at runtime on another instruction. To have proper instruction
+/// dependencies in the graph, instructions that depend on the check
+/// being done reference the [HCheck] instruction instead of the
+/// instruction itself.
abstract class HCheck extends HInstruction {
HCheck(inputs, type) : super(inputs, type) {
setUseGvn();
@@ -1512,10 +1498,9 @@
static const int ALWAYS_ABOVE_ZERO = 2;
static const int ALWAYS_BELOW_LENGTH = 3;
static const int ALWAYS_TRUE = 4;
- /**
- * Details which tests have been done statically during compilation.
- * Default is that all checks must be performed dynamically.
- */
+
+ /// Details which tests have been done statically during compilation.
+ /// Default is that all checks must be performed dynamically.
int staticChecks = FULL_CHECK;
HBoundsCheck(length, index, array, type)
@@ -1644,9 +1629,7 @@
/// The type arguments passed in this dynamic invocation.
List<DartType> get typeArguments;
- /**
- * Returns whether this call is on an interceptor object.
- */
+ /// Returns whether this call is on an interceptor object.
bool isCallOnInterceptor(JClosedWorld closedWorld) {
return isInterceptedCall && receiver.isInterceptor(closedWorld);
}
@@ -1776,7 +1759,7 @@
/// type arguments. See also [SsaFromAstMixin.currentInlinedInstantiations].
List<InterfaceType> instantiatedTypes;
- /** The first input must be the target. */
+ /// The first input must be the target.
HInvokeStatic(this.element, inputs, AbstractValue type, this.typeArguments,
{this.targetCanThrow: true, bool isIntercepted: false})
: super(inputs, type) {
@@ -1791,7 +1774,7 @@
}
class HInvokeSuper extends HInvokeStatic {
- /** The class where the call to super is being done. */
+ /// The class where the call to super is being done.
final ClassEntity caller;
final bool isSetter;
final Selector selector;
@@ -1816,9 +1799,7 @@
return isCallOnInterceptor(closedWorld) ? inputs[1] : inputs[0];
}
- /**
- * Returns whether this call is on an interceptor object.
- */
+ /// Returns whether this call is on an interceptor object.
bool isCallOnInterceptor(JClosedWorld closedWorld) {
return isInterceptedCall && receiver.isInterceptor(closedWorld);
}
@@ -1974,10 +1955,8 @@
String toString() => "GetLength()";
}
-/**
- * HReadModifyWrite is a late stage instruction for a field (property) update
- * via an assignment operation or pre- or post-increment.
- */
+/// HReadModifyWrite is a late stage instruction for a field (property) update
+/// via an assignment operation or pre- or post-increment.
class HReadModifyWrite extends HLateInstruction {
static const ASSIGN_OP = 0;
static const PRE_OP = 1;
@@ -2242,11 +2221,9 @@
bool dataEquals(HInstruction other) => true;
}
-/**
- * An [HSwitch] instruction has one input for the incoming
- * value, and one input per constant that it can switch on.
- * Its block has one successor per constant, and one for the default.
- */
+/// An [HSwitch] instruction has one input for the incoming
+/// value, and one input per constant that it can switch on.
+/// Its block has one successor per constant, and one for the default.
class HSwitch extends HControlFlow {
HSwitch(AbstractValueDomain domain, List<HInstruction> inputs)
: super(domain, inputs);
@@ -2254,11 +2231,9 @@
HConstant constant(int index) => inputs[index + 1];
HInstruction get expression => inputs[0];
- /**
- * Provides the target to jump to if none of the constants match
- * the expression. If the switch had no default case, this is the
- * following join-block.
- */
+ /// Provides the target to jump to if none of the constants match
+ /// the expression. If the switch had no default case, this is the
+ /// following join-block.
HBasicBlock get defaultTarget => block.successors.last;
accept(HVisitor visitor) => visitor.visitSwitch(this);
@@ -2551,11 +2526,9 @@
bool dataEquals(HInstruction other) => true;
}
-/**
- * An [HLocalValue] represents a local. Unlike [HParameterValue]s its
- * first use must be in an HLocalSet. That is, [HParameterValue]s have a
- * value from the start, whereas [HLocalValue]s need to be initialized first.
- */
+/// An [HLocalValue] represents a local. Unlike [HParameterValue]s its
+/// first use must be in an HLocalSet. That is, [HParameterValue]s have a
+/// value from the start, whereas [HLocalValue]s need to be initialized first.
class HLocalValue extends HInstruction {
HLocalValue(Entity variable, AbstractValue type)
: super(<HInstruction>[], type) {
@@ -2823,15 +2796,13 @@
}
}
-/**
- * A "one-shot" interceptor is a call to a synthetized method that
- * will fetch the interceptor of its first parameter, and make a call
- * on a given selector with the remaining parameters.
- *
- * In order to share the same optimizations with regular interceptor
- * calls, this class extends [HInvokeDynamic] and also has the null
- * constant as the first input.
- */
+/// A "one-shot" interceptor is a call to a synthetized method that
+/// will fetch the interceptor of its first parameter, and make a call
+/// on a given selector with the remaining parameters.
+///
+/// In order to share the same optimizations with regular interceptor
+/// calls, this class extends [HInvokeDynamic] and also has the null
+/// constant as the first input.
class HOneShotInterceptor extends HInvokeDynamic {
List<DartType> typeArguments;
Set<ClassEntity> interceptedClasses;
@@ -2855,7 +2826,7 @@
accept(HVisitor visitor) => visitor.visitOneShotInterceptor(this);
}
-/** An [HLazyStatic] is a static that is initialized lazily at first read. */
+/// An [HLazyStatic] is a static that is initialized lazily at first read.
class HLazyStatic extends HInstruction {
final FieldEntity element;
@@ -2904,10 +2875,8 @@
bool isAllocation(AbstractValueDomain domain) => true;
}
-/**
- * The primitive array indexing operation. Note that this instruction
- * does not throw because we generate the checks explicitly.
- */
+/// The primitive array indexing operation. Note that this instruction
+/// does not throw because we generate the checks explicitly.
class HIndex extends HInstruction {
final Selector selector;
HIndex(HInstruction receiver, HInstruction index, this.selector,
@@ -2939,10 +2908,8 @@
bool dataEquals(HIndex other) => true;
}
-/**
- * The primitive array assignment operation. Note that this instruction
- * does not throw because we generate the checks explicitly.
- */
+/// The primitive array assignment operation. Note that this instruction
+/// does not throw because we generate the checks explicitly.
class HIndexAssign extends HInstruction {
final Selector selector;
HIndexAssign(AbstractValueDomain domain, HInstruction receiver,
@@ -3065,11 +3032,9 @@
}
}
-/**
- * HIsViaInterceptor is a late-stage instruction for a type test that can be
- * done entirely on an interceptor. It is not a HCheck because the checked
- * input is not one of the inputs.
- */
+/// HIsViaInterceptor is a late-stage instruction for a type test that can be
+/// done entirely on an interceptor. It is not a HCheck because the checked
+/// input is not one of the inputs.
class HIsViaInterceptor extends HLateInstruction {
final DartType typeExpression;
HIsViaInterceptor(
@@ -3323,10 +3288,8 @@
toString() => "string concat";
}
-/**
- * The part of string interpolation which converts and interpolated expression
- * into a String value.
- */
+/// The part of string interpolation which converts and interpolated expression
+/// into a String value.
class HStringify extends HInstruction {
HStringify(HInstruction input, AbstractValue type)
: super(<HInstruction>[input], type) {
@@ -3338,7 +3301,7 @@
toString() => "stringify";
}
-/** Non-block-based (aka. traditional) loop information. */
+/// Non-block-based (aka. traditional) loop information.
class HLoopInformation {
final HBasicBlock header;
final List<HBasicBlock> blocks;
@@ -3346,7 +3309,7 @@
final List<LabelDefinition> labels;
final JumpTarget target;
- /** Corresponding block information for the loop. */
+ /// Corresponding block information for the loop.
HLoopBlockInformation loopBlockInformation;
HLoopInformation(this.header, this.target, this.labels)
@@ -3379,37 +3342,29 @@
}
}
-/**
- * Embedding of a [HBlockInformation] for block-structure based traversal
- * in a dominator based flow traversal by attaching it to a basic block.
- * To go back to dominator-based traversal, a [HSubGraphBlockInformation]
- * structure can be added in the block structure.
- */
+/// Embedding of a [HBlockInformation] for block-structure based traversal
+/// in a dominator based flow traversal by attaching it to a basic block.
+/// To go back to dominator-based traversal, a [HSubGraphBlockInformation]
+/// structure can be added in the block structure.
class HBlockFlow {
final HBlockInformation body;
final HBasicBlock continuation;
HBlockFlow(this.body, this.continuation);
}
-/**
- * Information about a syntactic-like structure.
- */
+/// Information about a syntactic-like structure.
abstract class HBlockInformation {
HBasicBlock get start;
HBasicBlock get end;
bool accept(HBlockInformationVisitor visitor);
}
-/**
- * Information about a statement-like structure.
- */
+/// Information about a statement-like structure.
abstract class HStatementInformation extends HBlockInformation {
bool accept(HStatementInformationVisitor visitor);
}
-/**
- * Information about an expression-like structure.
- */
+/// Information about an expression-like structure.
abstract class HExpressionInformation extends HBlockInformation {
bool accept(HExpressionInformationVisitor visitor);
HInstruction get conditionExpression;
@@ -3435,10 +3390,8 @@
abstract class HBlockInformationVisitor
implements HStatementInformationVisitor, HExpressionInformationVisitor {}
-/**
- * Generic class wrapping a [SubGraph] as a block-information until
- * all structures are handled properly.
- */
+/// Generic class wrapping a [SubGraph] as a block-information until
+/// all structures are handled properly.
class HSubGraphBlockInformation implements HStatementInformation {
final SubGraph subGraph;
HSubGraphBlockInformation(this.subGraph);
@@ -3450,10 +3403,8 @@
visitor.visitSubGraphInfo(this);
}
-/**
- * Generic class wrapping a [SubExpression] as a block-information until
- * expressions structures are handled properly.
- */
+/// Generic class wrapping a [SubExpression] as a block-information until
+/// expressions structures are handled properly.
class HSubExpressionBlockInformation implements HExpressionInformation {
final SubExpression subExpression;
HSubExpressionBlockInformation(this.subExpression);
@@ -3467,7 +3418,7 @@
visitor.visitSubExpressionInfo(this);
}
-/** A sequence of separate statements. */
+/// A sequence of separate statements.
class HStatementSequenceInformation implements HStatementInformation {
final List<HStatementInformation> statements;
HStatementSequenceInformation(this.statements);
diff --git a/pkg/compiler/lib/src/ssa/optimize.dart b/pkg/compiler/lib/src/ssa/optimize.dart
index dd6084d..40917cf 100644
--- a/pkg/compiler/lib/src/ssa/optimize.dart
+++ b/pkg/compiler/lib/src/ssa/optimize.dart
@@ -182,10 +182,8 @@
return false;
}
-/**
- * If both inputs to known operations are available execute the operation at
- * compile-time.
- */
+/// If both inputs to known operations are available execute the operation at
+/// compile-time.
class SsaInstructionSimplifier extends HBaseVisitor
implements OptimizationPhase {
// We don't produce constant-folded strings longer than this unless they have
@@ -2821,11 +2819,9 @@
}
}
-/**
- * Optimization phase that tries to eliminate memory loads (for example
- * [HFieldGet]), when it knows the value stored in that memory location, and
- * stores that overwrite with the same value.
- */
+/// Optimization phase that tries to eliminate memory loads (for example
+/// [HFieldGet]), when it knows the value stored in that memory location, and
+/// stores that overwrite with the same value.
class SsaLoadElimination extends HBaseVisitor implements OptimizationPhase {
final Compiler compiler;
final JClosedWorld closedWorld;
diff --git a/pkg/compiler/lib/src/ssa/ssa_branch_builder.dart b/pkg/compiler/lib/src/ssa/ssa_branch_builder.dart
index f6bfb90..5f2e064 100644
--- a/pkg/compiler/lib/src/ssa/ssa_branch_builder.dart
+++ b/pkg/compiler/lib/src/ssa/ssa_branch_builder.dart
@@ -58,10 +58,8 @@
new SubExpression(conditionBranch.block, conditionExitBlock);
}
- /**
- * Returns true if the locals of the [fromBranch] may be reused. A [:true:]
- * return value implies that [mayReuseFromLocals] was set to [:true:].
- */
+ /// Returns true if the locals of the [fromBranch] may be reused. A [:true:]
+ /// return value implies that [mayReuseFromLocals] was set to [:true:].
bool mergeLocals(SsaBranch fromBranch, SsaBranch toBranch,
{bool mayReuseFromLocals}) {
LocalsHandler fromLocals = fromBranch.exitLocals;
diff --git a/pkg/compiler/lib/src/ssa/ssa_tracer.dart b/pkg/compiler/lib/src/ssa/ssa_tracer.dart
index a4b3de8..ee7bc98 100644
--- a/pkg/compiler/lib/src/ssa/ssa_tracer.dart
+++ b/pkg/compiler/lib/src/ssa/ssa_tracer.dart
@@ -12,11 +12,9 @@
import '../world.dart' show JClosedWorld;
import 'nodes.dart';
-/**
- * Outputs SSA code in a format readable by Hydra IR.
- * Tracing is disabled by default, see ../tracer.dart for how
- * to enable it.
- */
+/// Outputs SSA code in a format readable by Hydra IR.
+/// Tracing is disabled by default, see ../tracer.dart for how
+/// to enable it.
class HTracer extends HGraphVisitor with TracerUtil {
final JClosedWorld closedWorld;
final Namer namer;
diff --git a/pkg/compiler/lib/src/ssa/validate.dart b/pkg/compiler/lib/src/ssa/validate.dart
index 31e9125..1f93b4e 100644
--- a/pkg/compiler/lib/src/ssa/validate.dart
+++ b/pkg/compiler/lib/src/ssa/validate.dart
@@ -132,7 +132,7 @@
super.visitBasicBlock(block);
}
- /** Returns how often [instruction] is contained in [instructions]. */
+ /// Returns how often [instruction] is contained in [instructions].
static int countInstruction(
List<HInstruction> instructions, HInstruction instruction) {
int result = 0;
@@ -142,11 +142,9 @@
return result;
}
- /**
- * Returns true if the predicate returns true for every instruction in the
- * list. The argument to [f] is an instruction with the count of how often
- * it appeared in the list [instructions].
- */
+ /// Returns true if the predicate returns true for every instruction in the
+ /// list. The argument to [f] is an instruction with the count of how often
+ /// it appeared in the list [instructions].
static bool everyInstruction(List<HInstruction> instructions, Function f) {
var copy = new List<HInstruction>.from(instructions);
// TODO(floitsch): there is currently no way to sort HInstructions before
diff --git a/pkg/compiler/lib/src/ssa/value_range_analyzer.dart b/pkg/compiler/lib/src/ssa/value_range_analyzer.dart
index acdfd27..a4bfd96 100644
--- a/pkg/compiler/lib/src/ssa/value_range_analyzer.dart
+++ b/pkg/compiler/lib/src/ssa/value_range_analyzer.dart
@@ -58,11 +58,9 @@
}
}
-/**
- * A [Value] represents both symbolic values like the value of a
- * parameter, or the length of an array, and concrete values, like
- * constants.
- */
+/// A [Value] represents both symbolic values like the value of a
+/// parameter, or the length of an array, and concrete values, like
+/// constants.
abstract class Value {
final ValueRangeInfo info;
const Value(this.info);
@@ -97,10 +95,8 @@
bool get isZero => false;
}
-/**
- * The [MarkerValue] class is used to recognize ranges of loop
- * updates.
- */
+/// The [MarkerValue] class is used to recognize ranges of loop
+/// updates.
class MarkerValue extends Value {
/// If [positive] is true (respectively false), the marker goes
/// to [MaxIntValue] (respectively [MinIntValue]) when being added
@@ -124,9 +120,7 @@
}
}
-/**
- * An [IntValue] contains a constant integer value.
- */
+/// An [IntValue] contains a constant integer value.
class IntValue extends Value {
final BigInt value;
@@ -192,10 +186,8 @@
bool get isZero => value == BigInt.zero;
}
-/**
- * The [MaxIntValue] represents the maximum value an integer can have,
- * which is currently +infinity.
- */
+/// The [MaxIntValue] represents the maximum value an integer can have,
+/// which is currently +infinity.
class MaxIntValue extends Value {
const MaxIntValue() : super(null);
Value operator +(Value other) => this;
@@ -208,10 +200,8 @@
bool get isPositive => true;
}
-/**
- * The [MinIntValue] represents the minimum value an integer can have,
- * which is currently -infinity.
- */
+/// The [MinIntValue] represents the minimum value an integer can have,
+/// which is currently -infinity.
class MinIntValue extends Value {
const MinIntValue() : super(null);
Value operator +(Value other) => this;
@@ -224,10 +214,8 @@
bool get isPositive => false;
}
-/**
- * The [UnknownValue] is the sentinel in our analysis to mark an
- * operation that could not be done because of too much complexity.
- */
+/// The [UnknownValue] is the sentinel in our analysis to mark an
+/// operation that could not be done because of too much complexity.
class UnknownValue extends Value {
const UnknownValue() : super(null);
Value operator +(Value other) => const UnknownValue();
@@ -240,9 +228,7 @@
String toString() => 'Unknown';
}
-/**
- * A symbolic value representing an [HInstruction].
- */
+/// A symbolic value representing an [HInstruction].
class InstructionValue extends Value {
final HInstruction instruction;
InstructionValue(this.instruction, info) : super(info);
@@ -293,18 +279,14 @@
String toString() => 'Instruction: $instruction';
}
-/**
- * Special value for instructions whose type is a positive integer.
- */
+/// Special value for instructions whose type is a positive integer.
class PositiveValue extends InstructionValue {
PositiveValue(HInstruction instruction, info) : super(instruction, info);
bool get isPositive => true;
}
-/**
- * Represents a binary operation on two [Value], where the operation
- * did not yield a canonical value.
- */
+/// Represents a binary operation on two [Value], where the operation
+/// did not yield a canonical value.
class BinaryOperationValue extends Value {
final Value left;
final Value right;
@@ -457,11 +439,9 @@
String toString() => '-$value';
}
-/**
- * A [Range] represents the possible integer values an instruction
- * can have, from its [lower] bound to its [upper] bound, both
- * included.
- */
+/// A [Range] represents the possible integer values an instruction
+/// can have, from its [lower] bound to its [upper] bound, both
+/// included.
class Range {
final Value lower;
final Value upper;
@@ -473,10 +453,8 @@
Range.unbound(info) : this(const MinIntValue(), const MaxIntValue(), info);
- /**
- * Checks if the given values are unknown, and creates a
- * range that does not have any unknown values.
- */
+ /// Checks if the given values are unknown, and creates a
+ /// range that does not have any unknown values.
Range.normalize(Value low, Value up, info)
: this(low == const UnknownValue() ? const MinIntValue() : low,
up == const UnknownValue() ? const MaxIntValue() : up, info);
@@ -579,25 +557,19 @@
String toString() => '[$lower, $upper]';
}
-/**
- * Visits the graph in dominator order, and computes value ranges for
- * integer instructions. While visiting the graph, this phase also
- * removes unnecessary bounds checks, and comparisons that are proven
- * to be true or false.
- */
+/// Visits the graph in dominator order, and computes value ranges for
+/// integer instructions. While visiting the graph, this phase also
+/// removes unnecessary bounds checks, and comparisons that are proven
+/// to be true or false.
class SsaValueRangeAnalyzer extends HBaseVisitor implements OptimizationPhase {
String get name => 'SSA value range builder';
- /**
- * List of [HRangeConversion] instructions created by the phase. We
- * save them here in order to remove them once the phase is done.
- */
+ /// List of [HRangeConversion] instructions created by the phase. We
+ /// save them here in order to remove them once the phase is done.
final List<HRangeConversion> conversions = <HRangeConversion>[];
- /**
- * Value ranges for integer instructions. This map gets populated by
- * the dominator tree visit.
- */
+ /// Value ranges for integer instructions. This map gets populated by
+ /// the dominator tree visit.
final Map<HInstruction, Range> ranges = new Map<HInstruction, Range>();
final JClosedWorld closedWorld;
@@ -1088,9 +1060,7 @@
}
}
-/**
- * Tries to find a range for the update instruction of a loop phi.
- */
+/// Tries to find a range for the update instruction of a loop phi.
class LoopUpdateRecognizer extends HBaseVisitor {
final JClosedWorld closedWorld;
final Map<HInstruction, Range> ranges;
diff --git a/pkg/compiler/lib/src/ssa/variable_allocator.dart b/pkg/compiler/lib/src/ssa/variable_allocator.dart
index 3bb3c85..6837537 100644
--- a/pkg/compiler/lib/src/ssa/variable_allocator.dart
+++ b/pkg/compiler/lib/src/ssa/variable_allocator.dart
@@ -6,9 +6,7 @@
import '../js_backend/js_backend.dart';
import 'nodes.dart';
-/**
- * The [LiveRange] class covers a range where an instruction is live.
- */
+/// The [LiveRange] class covers a range where an instruction is live.
class LiveRange {
final int start;
// [end] is not final because it can be updated due to loops.
@@ -20,14 +18,10 @@
String toString() => '[$start $end[';
}
-/**
- * The [LiveInterval] class contains the list of ranges where an
- * instruction is live.
- */
+/// The [LiveInterval] class contains the list of ranges where an
+/// instruction is live.
class LiveInterval {
- /**
- * The id where the instruction is defined.
- */
+ /// The id where the instruction is defined.
int start;
final List<LiveRange> ranges;
LiveInterval() : ranges = <LiveRange>[];
@@ -38,10 +32,8 @@
LiveInterval.forCheck(this.start, LiveInterval checkedInterval)
: ranges = checkedInterval.ranges;
- /**
- * Update all ranges that are contained in [from, to[ to
- * die at [to].
- */
+ /// Update all ranges that are contained in [from, to[ to
+ /// die at [to].
void loopUpdate(int from, int to) {
for (LiveRange range in ranges) {
if (from <= range.start && range.end < to) {
@@ -50,16 +42,12 @@
}
}
- /**
- * Add a new range to this interval.
- */
+ /// Add a new range to this interval.
void add(LiveRange interval) {
ranges.add(interval);
}
- /**
- * Returns true if one of the ranges of this interval dies at [at].
- */
+ /// Returns true if one of the ranges of this interval dies at [at].
bool diesAt(int at) {
for (LiveRange range in ranges) {
if (range.end == at) return true;
@@ -74,53 +62,39 @@
}
}
-/**
- * The [LiveEnvironment] class contains the liveIn set of a basic
- * block. A liveIn set of a block contains the instructions that are
- * live when entering that block.
- */
+/// The [LiveEnvironment] class contains the liveIn set of a basic
+/// block. A liveIn set of a block contains the instructions that are
+/// live when entering that block.
class LiveEnvironment {
- /**
- * The instruction id where the basic block starts. See
- * [SsaLiveIntervalBuilder.instructionId].
- */
+ /// The instruction id where the basic block starts. See
+ /// [SsaLiveIntervalBuilder.instructionId].
int startId;
- /**
- * The instruction id where the basic block ends.
- */
+ /// The instruction id where the basic block ends.
final int endId;
- /**
- * Loop markers that will be updated once the loop header is
- * visited. The liveIn set of the loop header will be merged into this
- * environment. [loopMarkers] is a mapping from block header to the
- * end instruction id of the loop exit block.
- */
+ /// Loop markers that will be updated once the loop header is
+ /// visited. The liveIn set of the loop header will be merged into this
+ /// environment. [loopMarkers] is a mapping from block header to the
+ /// end instruction id of the loop exit block.
final Map<HBasicBlock, int> loopMarkers;
- /**
- * The instructions that are live in this basic block. The values of
- * the map contain the instruction ids where the instructions die.
- * It will be used when adding a range to the live interval of an
- * instruction.
- */
+ /// The instructions that are live in this basic block. The values of
+ /// the map contain the instruction ids where the instructions die.
+ /// It will be used when adding a range to the live interval of an
+ /// instruction.
final Map<HInstruction, int> liveInstructions;
- /**
- * Map containing the live intervals of instructions.
- */
+ /// Map containing the live intervals of instructions.
final Map<HInstruction, LiveInterval> liveIntervals;
LiveEnvironment(this.liveIntervals, this.endId)
: liveInstructions = new Map<HInstruction, int>(),
loopMarkers = new Map<HBasicBlock, int>();
- /**
- * Remove an instruction from the liveIn set. This method also
- * updates the live interval of [instruction] to contain the new
- * range: [id, / id contained in [liveInstructions] /].
- */
+ /// Remove an instruction from the liveIn set. This method also
+ /// updates the live interval of [instruction] to contain the new
+ /// range: [id, / id contained in [liveInstructions] /].
void remove(HInstruction instruction, int id) {
LiveInterval interval =
liveIntervals.putIfAbsent(instruction, () => new LiveInterval());
@@ -132,20 +106,16 @@
liveInstructions.remove(instruction);
}
- /**
- * Add [instruction] to the liveIn set. If the instruction is not
- * already in the set, we save the id where it dies.
- */
+ /// Add [instruction] to the liveIn set. If the instruction is not
+ /// already in the set, we save the id where it dies.
void add(HInstruction instruction, int userId) {
// Note that we are visiting the graph in post-dominator order, so
// the first time we see a variable is when it dies.
liveInstructions.putIfAbsent(instruction, () => userId);
}
- /**
- * Merge this environment with [other]. Update the end id of
- * instructions in case they are different between this and [other].
- */
+ /// Merge this environment with [other]. Update the end id of
+ /// instructions in case they are different between this and [other].
void mergeWith(LiveEnvironment other) {
other.liveInstructions.forEach((HInstruction instruction, int existingId) {
// If both environments have the same instruction id of where
@@ -180,31 +150,23 @@
String toString() => liveInstructions.toString();
}
-/**
- * Builds the live intervals of each instruction. The algorithm visits
- * the graph post-dominator tree to find the last uses of an
- * instruction, and computes the liveIns of each basic block.
- */
+/// Builds the live intervals of each instruction. The algorithm visits
+/// the graph post-dominator tree to find the last uses of an
+/// instruction, and computes the liveIns of each basic block.
class SsaLiveIntervalBuilder extends HBaseVisitor {
final Set<HInstruction> generateAtUseSite;
final Set<HInstruction> controlFlowOperators;
- /**
- * A counter to assign start and end ids to live ranges. The initial
- * value is not relevant. Note that instructionId goes downward to ease
- * reasoning about live ranges (the first instruction of a graph has
- * the lowest id).
- */
+ /// A counter to assign start and end ids to live ranges. The initial
+ /// value is not relevant. Note that instructionId goes downward to ease
+ /// reasoning about live ranges (the first instruction of a graph has
+ /// the lowest id).
int instructionId = 0;
- /**
- * The liveIns of basic blocks.
- */
+ /// The liveIns of basic blocks.
final Map<HBasicBlock, LiveEnvironment> liveInstructions;
- /**
- * The live intervals of instructions.
- */
+ /// The live intervals of instructions.
final Map<HInstruction, LiveInterval> liveIntervals;
SsaLiveIntervalBuilder(this.generateAtUseSite, this.controlFlowOperators)
@@ -384,11 +346,9 @@
}
}
-/**
- * Represents a copy from one instruction to another. The codegen
- * also uses this class to represent a copy from one variable to
- * another.
- */
+/// Represents a copy from one instruction to another. The codegen
+/// also uses this class to represent a copy from one variable to
+/// another.
class Copy<T> {
final T source;
final T destination;
@@ -398,20 +358,14 @@
String toString() => '$destination <- $source';
}
-/**
- * A copy handler contains the copies that a basic block needs to do
- * after executing all its instructions.
- */
+/// A copy handler contains the copies that a basic block needs to do
+/// after executing all its instructions.
class CopyHandler {
- /**
- * The copies from an instruction to a phi of the successor.
- */
+ /// The copies from an instruction to a phi of the successor.
final List<Copy<HInstruction>> copies;
- /**
- * Assignments from an instruction that does not need a name (e.g. a
- * constant) to the phi of a successor.
- */
+ /// Assignments from an instruction that does not need a name (e.g. a
+ /// constant) to the phi of a successor.
final List<Copy<HInstruction>> assignments;
CopyHandler()
@@ -431,21 +385,18 @@
bool get isEmpty => copies.isEmpty && assignments.isEmpty;
}
-/**
- * Contains the mapping between instructions and their names for code
- * generation, as well as the [CopyHandler] for each basic block.
- */
+/// Contains the mapping between instructions and their names for code
+/// generation, as well as the [CopyHandler] for each basic block.
class VariableNames {
final Map<HInstruction, String> ownName;
final Map<HBasicBlock, CopyHandler> copyHandlers;
// Used to control heuristic that determines how local variables are declared.
final Set<String> allUsedNames;
- /**
- * Name that is used as a temporary to break cycles in
- * parallel copies. We make sure this name is not being used
- * anywhere by reserving it when we allocate names for instructions.
- */
+
+ /// Name that is used as a temporary to break cycles in
+ /// parallel copies. We make sure this name is not being used
+ /// anywhere by reserving it when we allocate names for instructions.
final String swapTemp;
String getSwapTemp() {
@@ -488,9 +439,7 @@
}
}
-/**
- * Allocates variable names for instructions, making sure they don't collide.
- */
+/// Allocates variable names for instructions, making sure they don't collide.
class VariableNamer {
final VariableNames names;
final Namer _namer;
@@ -586,9 +535,7 @@
return name;
}
- /**
- * Frees [instruction]'s name so it can be used for other instructions.
- */
+ /// Frees [instruction]'s name so it can be used for other instructions.
void freeName(HInstruction instruction) {
String ownName = names.ownName[instruction];
if (ownName != null) {
@@ -604,18 +551,16 @@
}
}
-/**
- * Visits all blocks in the graph, sets names to instructions, and
- * creates the [CopyHandler] for each block. This class needs to have
- * the liveIns set as well as all the live intervals of instructions.
- * It visits the graph in dominator order, so that at each entry of a
- * block, the instructions in its liveIns set have names.
- *
- * When visiting a block, it goes through all instructions. For each
- * instruction, it frees the names of the inputs that die at that
- * instruction, and allocates a name to the instruction. For each phi,
- * it adds a copy to the CopyHandler of the corresponding predecessor.
- */
+/// Visits all blocks in the graph, sets names to instructions, and
+/// creates the [CopyHandler] for each block. This class needs to have
+/// the liveIns set as well as all the live intervals of instructions.
+/// It visits the graph in dominator order, so that at each entry of a
+/// block, the instructions in its liveIns set have names.
+///
+/// When visiting a block, it goes through all instructions. For each
+/// instruction, it frees the names of the inputs that die at that
+/// instruction, and allocates a name to the instruction. For each phi,
+/// it adds a copy to the CopyHandler of the corresponding predecessor.
class SsaVariableAllocator extends HBaseVisitor {
final Namer _namer;
final Map<HBasicBlock, LiveEnvironment> liveInstructions;
@@ -645,10 +590,8 @@
});
}
- /**
- * Returns whether [instruction] needs a name. Instructions that
- * have no users or that are generated at use site do not need a name.
- */
+ /// Returns whether [instruction] needs a name. Instructions that
+ /// have no users or that are generated at use site do not need a name.
bool needsName(instruction) {
if (instruction is HThis) return false;
if (instruction is HParameterValue) return true;
@@ -657,9 +600,7 @@
return !instruction.nonCheck().isCodeMotionInvariant();
}
- /**
- * Returns whether [instruction] dies at the instruction [at].
- */
+ /// Returns whether [instruction] dies at the instruction [at].
bool diesAt(HInstruction instruction, HInstruction at) {
LiveInterval atInterval = liveIntervals[at];
LiveInterval instructionInterval = liveIntervals[instruction];
diff --git a/pkg/compiler/lib/src/tracer.dart b/pkg/compiler/lib/src/tracer.dart
index 9a8f51c..f4e7870 100644
--- a/pkg/compiler/lib/src/tracer.dart
+++ b/pkg/compiler/lib/src/tracer.dart
@@ -11,10 +11,8 @@
import 'util/util.dart' show Indentation;
import 'world.dart' show JClosedWorld;
-/**
- * If non-null, we only trace methods whose name match the regexp defined by the
- * given pattern.
- */
+/// If non-null, we only trace methods whose name match the regexp defined by
+/// the given pattern.
String get TRACE_FILTER_PATTERN =>
TRACE_FILTER_PATTERN_FROM_ENVIRONMENT ?? TRACE_FILTER_PATTERN_FOR_TEST;
@@ -22,10 +20,8 @@
const String.fromEnvironment("DUMP_IR");
String TRACE_FILTER_PATTERN_FOR_TEST;
-/**
- * Dumps the intermediate representation after each phase in a format
- * readable by IR Hydra.
- */
+/// Dumps the intermediate representation after each phase in a format
+/// readable by IR Hydra.
class Tracer extends TracerUtil {
final JClosedWorld closedWorld;
final Namer namer;
diff --git a/pkg/compiler/lib/src/universe/class_hierarchy.dart b/pkg/compiler/lib/src/universe/class_hierarchy.dart
index 181714f..e5707ad 100644
--- a/pkg/compiler/lib/src/universe/class_hierarchy.dart
+++ b/pkg/compiler/lib/src/universe/class_hierarchy.dart
@@ -150,8 +150,8 @@
}
class ClassHierarchyImpl implements ClassHierarchy {
- /// Tag used for identifying serialized [ClassHierarchy] objects in a debugging
- /// data stream.
+ /// Tag used for identifying serialized [ClassHierarchy] objects in a
+ /// debugging data stream.
static const String tag = 'class-hierarchy';
final CommonElements _commonElements;
diff --git a/pkg/compiler/lib/src/universe/codegen_world_builder.dart b/pkg/compiler/lib/src/universe/codegen_world_builder.dart
index 395639e..2c9980d 100644
--- a/pkg/compiler/lib/src/universe/codegen_world_builder.dart
+++ b/pkg/compiler/lib/src/universe/codegen_world_builder.dart
@@ -138,11 +138,9 @@
/// Invariant: Elements are declaration elements.
final Set<FieldEntity> allReferencedStaticFields = new Set<FieldEntity>();
- /**
- * Documentation wanted -- johnniwinther
- *
- * Invariant: Elements are declaration elements.
- */
+ /// Documentation wanted -- johnniwinther
+ ///
+ /// Invariant: Elements are declaration elements.
final Set<FunctionEntity> staticFunctionsNeedingGetter =
new Set<FunctionEntity>();
final Set<FunctionEntity> methodsNeedingSuperGetter =
diff --git a/pkg/compiler/lib/src/universe/resolution_world_builder.dart b/pkg/compiler/lib/src/universe/resolution_world_builder.dart
index 6119207..fee6d25 100644
--- a/pkg/compiler/lib/src/universe/resolution_world_builder.dart
+++ b/pkg/compiler/lib/src/universe/resolution_world_builder.dart
@@ -311,11 +311,9 @@
/// Invariant: Elements are declaration elements.
final Set<FieldEntity> allReferencedStaticFields = new Set<FieldEntity>();
- /**
- * Documentation wanted -- johnniwinther
- *
- * Invariant: Elements are declaration elements.
- */
+ /// Documentation wanted -- johnniwinther
+ ///
+ /// Invariant: Elements are declaration elements.
final Set<FunctionEntity> methodsNeedingSuperGetter =
new Set<FunctionEntity>();
final Map<String, Map<Selector, SelectorConstraints>> _invokedNames =
diff --git a/pkg/compiler/lib/src/universe/selector.dart b/pkg/compiler/lib/src/universe/selector.dart
index 47f974e..0696300 100644
--- a/pkg/compiler/lib/src/universe/selector.dart
+++ b/pkg/compiler/lib/src/universe/selector.dart
@@ -233,9 +233,7 @@
bool get isOperator => kind == SelectorKind.OPERATOR;
bool get isUnaryOperator => isOperator && argumentCount == 0;
- /**
- * The member name for invocation mirrors created from this selector.
- */
+ /// The member name for invocation mirrors created from this selector.
String get invocationMirrorMemberName => isSetter ? '$name=' : name;
int get invocationMirrorKind {
diff --git a/pkg/compiler/lib/src/universe/use.dart b/pkg/compiler/lib/src/universe/use.dart
index b5fc867..9ba793f 100644
--- a/pkg/compiler/lib/src/universe/use.dart
+++ b/pkg/compiler/lib/src/universe/use.dart
@@ -33,8 +33,8 @@
}
/// The use of a dynamic property. [selector] defined the name and kind of the
-/// property and [receiverConstraint] defines the known constraint for the object on which
-/// the property is accessed.
+/// property and [receiverConstraint] defines the known constraint for the
+/// object on which the property is accessed.
class DynamicUse {
final Selector selector;
diff --git a/pkg/compiler/lib/src/util/indentation.dart b/pkg/compiler/lib/src/util/indentation.dart
index 9709f78..fb7cc21 100644
--- a/pkg/compiler/lib/src/util/indentation.dart
+++ b/pkg/compiler/lib/src/util/indentation.dart
@@ -69,9 +69,7 @@
return tag;
}
- /**
- * Adds given string to result string.
- */
+ /// Adds given string to result string.
void add(String string) {
sb.write(string);
}
@@ -79,12 +77,10 @@
/// Adds default parameters for [node] into [params].
void addDefaultParameters(N node, Map params) {}
- /**
- * Adds given node type to result string.
- * The method "opens" the node, meaning that all output after calling
- * this method and before calling closeNode() will represent contents
- * of given node.
- */
+ /// Adds given node type to result string.
+ /// The method "opens" the node, meaning that all output after calling
+ /// this method and before calling closeNode() will represent contents
+ /// of given node.
void openNode(N node, String type, [Map params]) {
if (params == null) params = new Map();
addCurrentIndent();
@@ -95,9 +91,7 @@
pushTag(type);
}
- /**
- * Adds given node to result string.
- */
+ /// Adds given node to result string.
void openAndCloseNode(N node, String type, [Map params]) {
if (params == null) params = {};
addCurrentIndent();
@@ -107,9 +101,7 @@
sb.write("/>\n");
}
- /**
- * Closes current node type.
- */
+ /// Closes current node type.
void closeNode() {
String tag = popTag();
addCurrentIndent();
diff --git a/pkg/compiler/lib/src/util/util.dart b/pkg/compiler/lib/src/util/util.dart
index 297efca..785253d 100644
--- a/pkg/compiler/lib/src/util/util.dart
+++ b/pkg/compiler/lib/src/util/util.dart
@@ -114,10 +114,8 @@
return a.length == b.length && a.containsAll(b) && b.containsAll(a);
}
-/**
- * File name prefix used to shorten the file name in stack traces printed by
- * [trace].
- */
+/// File name prefix used to shorten the file name in stack traces printed by
+/// [trace].
String stackTraceFilePrefix = null;
/// Writes the characters of [string] on [buffer]. The characters
