Replace Backend with JavaScriptBackend.

pkg/compiler/lib/src/js_backend/backend.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // 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.
 
 library js_backend.backend;
 
 import 'dart:async' show Future;
 
 import 'package:js_runtime/shared/embedded_names.dart' as embeddedNames;
 
 import '../closure.dart';
 import '../common.dart';
 import '../common/backend_api.dart'
-    show
-        Backend,
-        BackendClasses,
-        ImpactTransformer,
-        ForeignResolver,
-        NativeRegistry;
+    show BackendClasses, ImpactTransformer, ForeignResolver, NativeRegistry;
 import '../common/codegen.dart' show CodegenImpact, CodegenWorkItem;
 import '../common/names.dart' show Identifiers, Uris;
-import '../common/resolution.dart' show Frontend, Resolution, ResolutionImpact;
+import '../common/resolution.dart'
+    show Frontend, Resolution, ResolutionImpact, Target;
 import '../common/tasks.dart' show CompilerTask;
 import '../compiler.dart' show Compiler;
 import '../constants/constant_system.dart';
 import '../constants/expressions.dart';
 import '../constants/values.dart';
 import '../core_types.dart' show CommonElements;
 import '../deferred_load.dart' show DeferredLoadTask;
 import '../dump_info.dart' show DumpInfoTask;
 import '../elements/elements.dart';
 import '../elements/entities.dart';
 import '../elements/resolution_types.dart';
 import '../elements/types.dart';
 import '../enqueue.dart'
-    show Enqueuer, ResolutionEnqueuer, TreeShakingEnqueuerStrategy;
+    show Enqueuer, EnqueueTask, ResolutionEnqueuer, TreeShakingEnqueuerStrategy;
 import '../io/position_information.dart' show PositionSourceInformationStrategy;
 import '../io/source_information.dart' show SourceInformationStrategy;
 import '../io/start_end_information.dart'
     show StartEndSourceInformationStrategy;
 import '../js/js.dart' as jsAst;
 import '../js/js.dart' show js;
 import '../js/js_source_mapping.dart' show JavaScriptSourceInformationStrategy;
 import '../js/rewrite_async.dart';
 import '../js_emitter/js_emitter.dart' show CodeEmitterTask;
 import '../library_loader.dart' show LibraryLoader, LoadedLibraries;
 import '../native/native.dart' as native;
+import '../patch_parser.dart'
+    show checkNativeAnnotation, checkJsInteropAnnotation;
 import '../ssa/ssa.dart' show SsaFunctionCompiler;
 import '../tracer.dart';
 import '../tree/tree.dart';
 import '../types/types.dart';
 import '../universe/call_structure.dart' show CallStructure;
 import '../universe/feature.dart';
 import '../universe/selector.dart' show Selector;
 import '../universe/world_builder.dart';
 import '../universe/use.dart'
     show DynamicUse, StaticUse, StaticUseKind, TypeUse, TypeUseKind;
@@ skipping 239 matching lines @@
   }
 }
 
 enum SyntheticConstantKind {
   DUMMY_INTERCEPTOR,
   EMPTY_VALUE,
   TYPEVARIABLE_REFERENCE, // Reference to a type in reflection data.
   NAME
 }
 
-class JavaScriptBackend extends Backend {
+class JavaScriptBackend extends Target {
+  final Compiler compiler;
+
   String get patchVersion => emitter.patchVersion;
 
+  /// Returns true if the backend supports reflection.
   bool get supportsReflection => emitter.supportsReflection;
 
   final Annotations annotations;
 
   /// Set of classes that need to be considered for reflection although not
   /// otherwise visible during resolution.
   Iterable<ClassElement> get classesRequiredForReflection {
     // TODO(herhut): Clean this up when classes needed for rti are tracked.
     return [helpers.closureClass, helpers.jsIndexableClass];
   }
@@ skipping 203 matching lines @@
 
   /// Support for classifying `noSuchMethod` implementations.
   NoSuchMethodRegistry noSuchMethodRegistry;
 
   /// Resolution and codegen support for computing reflectable elements.
   MirrorsAnalysis mirrorsAnalysis;
 
   /// Builds kernel representation for the program.
   KernelTask kernelTask;
 
+  /// The compiler task responsible for the compilation of constants for both
+  /// the frontend and the backend.
   JavaScriptConstantTask constantCompilerTask;
 
+  /// Backend transformation methods for the world impacts.
   JavaScriptImpactTransformer impactTransformer;
 
   PatchResolverTask patchResolverTask;
 
+  /// Whether or not `noSuchMethod` support has been enabled.
   bool enabledNoSuchMethod = false;
   bool _noSuchMethodEnabledForCodegen = false;
 
+  /// The strategy used for collecting and emitting source information.
   SourceInformationStrategy sourceInformationStrategy;
 
+  /// Interface for serialization of backend specific data.
   JavaScriptBackendSerialization serialization;
 
   StagedWorldImpactBuilder constantImpactsForResolution =
       new StagedWorldImpactBuilder();
 
   StagedWorldImpactBuilder constantImpactsForCodegen =
       new StagedWorldImpactBuilder();
 
   final NativeData nativeData = new NativeData();
 
   BackendHelpers helpers;
   final BackendImpacts impacts;
+
+  /// Common classes used by the backend.
   BackendClasses backendClasses;
 
+  /// Backend access to the front-end.
   final JSFrontendAccess frontend;
 
   Tracer tracer;
 
   JavaScriptBackend(Compiler compiler,
       {bool generateSourceMap: true,
       bool useStartupEmitter: false,
       bool useNewSourceInfo: false,
       bool useKernel: false})
       : oneShotInterceptors = new Map<jsAst.Name, Selector>(),
         interceptedElements = new Map<String, Set<Element>>(),
         rti = new _RuntimeTypes(compiler),
         rtiEncoder = new _RuntimeTypesEncoder(compiler),
         specializedGetInterceptors = new Map<jsAst.Name, Set<ClassElement>>(),
         annotations = new Annotations(compiler),
         this.sourceInformationStrategy = generateSourceMap
             ? (useNewSourceInfo
                 ? new PositionSourceInformationStrategy()
                 : const StartEndSourceInformationStrategy())
             : const JavaScriptSourceInformationStrategy(),
         impacts = new BackendImpacts(compiler),
         frontend = new JSFrontendAccess(compiler),
-        super(compiler) {
+        this.compiler = compiler {
     helpers =
         new BackendHelpers(compiler.elementEnvironment, this, commonElements);
     emitter =
         new CodeEmitterTask(compiler, generateSourceMap, useStartupEmitter);
     typeVariableHandler = new TypeVariableHandler(compiler);
     customElementsAnalysis = new CustomElementsAnalysis(this);
     lookupMapAnalysis = new LookupMapAnalysis(this, reporter);
     jsInteropAnalysis = new JsInteropAnalysis(this);
     mirrorsAnalysis = new MirrorsAnalysis(this, compiler.resolution);
 
     noSuchMethodRegistry = new NoSuchMethodRegistry(this);
     kernelTask = new KernelTask(compiler);
     constantCompilerTask = new JavaScriptConstantTask(compiler);
     impactTransformer = new JavaScriptImpactTransformer(this);
     patchResolverTask = new PatchResolverTask(compiler);
     functionCompiler =
         new SsaFunctionCompiler(this, sourceInformationStrategy, useKernel);
     serialization = new JavaScriptBackendSerialization(this);
     backendClasses = new JavaScriptBackendClasses(helpers);
   }
 
+  /// The [ConstantSystem] used to interpret compile-time constants for this
+  /// backend.
   ConstantSystem get constantSystem => constants.constantSystem;
 
   DiagnosticReporter get reporter => compiler.reporter;
 
   CommonElements get commonElements => compiler.commonElements;
 
   Resolution get resolution => compiler.resolution;
 
   /// Returns constant environment for the JavaScript interpretation of the
   /// constants.
@@ skipping 56 matching lines @@
       // add both to the list of helpers.
       helpersUsed.add(element.implementation);
     }
     return element;
   }
 
   bool _isValidBackendUse(Element element) {
     assert(invariant(element, element.isDeclaration, message: ""));
     if (element is ConstructorElement &&
         (element == helpers.streamIteratorConstructor ||
-        compiler.commonElements.isSymbolConstructor(element) ||
-        helpers.isSymbolValidatedConstructor(element) ||
-        element == helpers.syncCompleterConstructor)) {
-    // TODO(johnniwinther): These are valid but we could be more precise.
-    return true;
+            compiler.commonElements.isSymbolConstructor(element) ||
+            helpers.isSymbolValidatedConstructor(element) ||
+            element == helpers.syncCompleterConstructor)) {
+      // TODO(johnniwinther): These are valid but we could be more precise.
+      return true;
     } else if (element == commonElements.symbolClass ||
         element == helpers.objectNoSuchMethod) {
       // TODO(johnniwinther): These are valid but we could be more precise.
       return true;
     } else if (element.implementationLibrary.isPatch ||
         // Needed to detect deserialized injected elements, that is
         // element declared in patch files.
         (element.library.isPlatformLibrary &&
             element.sourcePosition.uri.path
                 .contains('_internal/js_runtime/lib/')) ||
@@ skipping 34 matching lines @@
     if (element.isField) {
       if (Elements.isStaticOrTopLevel(element) &&
           (element.isFinal || element.isConst)) {
         return false;
       }
     }
 
     return isAccessibleByReflection(element.declaration);
   }
 
+  /// Returns true if global optimizations such as type inferencing
+  /// can apply to this element. One category of elements that do not
+  /// apply is runtime helpers that the backend calls, but the
+  /// optimizations don't see those calls.
   bool canBeUsedForGlobalOptimizations(Element element) {
     return !usedByBackend(element) && !invokedReflectively(element);
   }
 
   bool isInterceptorClass(ClassElement element) {
     if (element == null) return false;
     if (isNativeOrExtendsNative(element)) return true;
     if (interceptedClasses.contains(element)) return true;
     if (classesMixedIntoInterceptedClasses.contains(element)) return true;
     return false;
@@ skipping 27 matching lines @@
     return !selector.isGetter;
   }
 
   /**
    * Returns `true` if [member] is called from a subclass via `super`.
    */
   bool isAliasedSuperMember(FunctionElement member) {
     return aliasedSuperMembers.contains(member);
   }
 
-  /// Returns `true` if [element] is part of JsInterop.
+  /// Returns `true` if [element] is implemented via typed JavaScript interop.
   @override
   bool isJsInterop(Element element) => nativeData.isJsInterop(element);
 
   /// Returns `true` if [element] is a JsInterop class.
   bool isJsInteropClass(ClassElement element) => isJsInterop(element);
 
   /// Returns `true` if [element] is a JsInterop method.
   bool isJsInteropMethod(MethodElement element) => isJsInterop(element);
 
   /// Whether [element] corresponds to a native JavaScript construct either
@@ skipping 254 matching lines @@
     jsAst.Name name = namer.nameForGetInterceptor(classes);
     if (classes.contains(helpers.jsInterceptorClass)) {
       // We can't use a specialized [getInterceptorMethod], so we make
       // sure we emit the one with all checks.
       specializedGetInterceptors[name] = interceptedClasses;
     } else {
       specializedGetInterceptors[name] = classes;
     }
   }
 
+  /// Called during codegen when [constant] has been used.
   void computeImpactForCompileTimeConstant(ConstantValue constant,
       WorldImpactBuilder impactBuilder, bool isForResolution) {
     computeImpactForCompileTimeConstantInternal(
         constant, impactBuilder, isForResolution);
 
     if (!isForResolution && lookupMapAnalysis.isLookupMap(constant)) {
       // Note: internally, this registration will temporarily remove the
       // constant dependencies and add them later on-demand.
       lookupMapAnalysis.registerLookupMapReference(constant);
     }
@@ skipping 52 matching lines @@
         // constant emitter will generate a call to the createRuntimeType
         // helper so we register a use of that.
         impactBuilder.registerStaticUse(new StaticUse.staticInvoke(
             // TODO(johnniwinther): Find the right [CallStructure].
             helpers.createRuntimeType,
             null));
       }
     }
   }
 
+  /// Called to notify to the backend that a class is being instantiated. Any
+  /// backend specific [WorldImpact] of this is returned.
   WorldImpact registerInstantiatedClass(ClassElement cls,
       {bool forResolution}) {
     return _processClass(cls, forResolution: forResolution);
   }
 
+  /// Called to notify to the backend that a class is implemented by an
+  /// instantiated class. Any backend specific [WorldImpact] of this is
+  /// returned.
   WorldImpact registerImplementedClass(ClassElement cls, {bool forResolution}) {
     return _processClass(cls, forResolution: forResolution);
   }
 
   WorldImpact _processClass(ClassElement cls, {bool forResolution}) {
     WorldImpactBuilderImpl impactBuilder = new WorldImpactBuilderImpl();
     if (!cls.typeVariables.isEmpty) {
       typeVariableHandler.registerClassWithTypeVariables(cls,
           forResolution: forResolution);
     }
@@ skipping 112 matching lines @@
 
     customElementsAnalysis.registerInstantiatedClass(cls,
         forResolution: forResolution);
     if (!forResolution) {
       lookupMapAnalysis.registerInstantiatedClass(cls);
     }
 
     return impactBuilder;
   }
 
+  /// Called to instruct to the backend register [type] as instantiated on
+  /// [enqueuer].
   void registerInstantiatedType(ResolutionInterfaceType type) {
     lookupMapAnalysis.registerInstantiatedType(type);
   }
 
-  @override
+  /// Compute the [WorldImpact] for backend helper methods.
   WorldImpact computeHelpersImpact() {
     assert(helpers.interceptorsLibrary != null);
     WorldImpactBuilderImpl impactBuilder = new WorldImpactBuilderImpl();
     // TODO(ngeoffray): Not enqueuing those two classes currently make
     // the compiler potentially crash. However, any reasonable program
     // will instantiate those two classes.
     addInterceptors(helpers.jsBoolClass, impactBuilder, forResolution: true);
     addInterceptors(helpers.jsNullClass, impactBuilder, forResolution: true);
     if (compiler.options.enableTypeAssertions) {
       impactTransformer.registerBackendImpact(
           impactBuilder, impacts.enableTypeAssertions);
     }
 
     if (TRACE_CALLS) {
       impactTransformer.registerBackendImpact(
           impactBuilder, impacts.traceHelper);
     }
     impactTransformer.registerBackendImpact(
         impactBuilder, impacts.assertUnreachable);
     _registerCheckedModeHelpers(impactBuilder);
     return impactBuilder;
   }
 
-  onResolutionComplete(
+  void onResolutionComplete(
       ClosedWorld closedWorld, ClosedWorldRefiner closedWorldRefiner) {
     for (Entity entity in compiler.enqueuer.resolution.processedEntities) {
       processAnnotations(entity, closedWorldRefiner);
     }
     computeMembersNeededForReflection(closedWorld);
     rti.computeClassesNeedingRti(
         compiler.enqueuer.resolution.worldBuilder, closedWorld);
     _registeredMetadata.clear();
   }
 
-  onTypeInferenceComplete() {
-    super.onTypeInferenceComplete();
+  void onTypeInferenceComplete() {
     noSuchMethodRegistry.onTypeInferenceComplete();
   }
 
   /// Called to register that an instantiated generic class has a call method.
   /// Any backend specific [WorldImpact] of this is returned.
   ///
   /// Note: The [callMethod] is registered even thought it doesn't reference
   /// the type variables.
   WorldImpact registerCallMethodWithFreeTypeVariables(Element callMethod,
       {bool forResolution}) {
     if (forResolution || methodNeedsRti(callMethod)) {
       return _registerComputeSignature();
     }
     return const WorldImpact();
   }
 
+  /// Called to instruct the backend to register that a closure exists for a
+  /// function on an instantiated generic class. Any backend specific
+  /// [WorldImpact] of this is returned.
   WorldImpact registerClosureWithFreeTypeVariables(Element closure,
       {bool forResolution}) {
     if (forResolution || methodNeedsRti(closure)) {
       return _registerComputeSignature();
     }
     return const WorldImpact();
   }
 
+  /// Called to register that a member has been closurized. Any backend specific
+  /// [WorldImpact] of this is returned.
   WorldImpact registerBoundClosure() {
     return impactTransformer.createImpactFor(impacts.memberClosure);
   }
 
+  /// Called to register that a static function has been closurized. Any backend
+  /// specific [WorldImpact] of this is returned.
   WorldImpact registerGetOfStaticFunction() {
     return impactTransformer.createImpactFor(impacts.staticClosure);
   }
 
   WorldImpact _registerComputeSignature() {
     return impactTransformer.createImpactFor(impacts.computeSignature);
   }
 
   /// Called to register that the `runtimeType` property has been accessed. Any
   /// backend specific [WorldImpact] of this is returned.
   WorldImpact registerRuntimeType() {
     return impactTransformer.createImpactFor(impacts.runtimeTypeSupport);
   }
 
+  /// Register a runtime type variable bound tests between [typeArgument] and
+  /// [bound].
   void registerTypeVariableBoundsSubtypeCheck(
       ResolutionDartType typeArgument, ResolutionDartType bound) {
     rti.registerTypeVariableBoundsSubtypeCheck(typeArgument, bound);
   }
 
+  /// Returns the [WorldImpact] of enabling deferred loading.
   WorldImpact computeDeferredLoadingImpact() {
     return impactTransformer.createImpactFor(impacts.deferredLoading);
   }
 
   /// Called to register a `noSuchMethod` implementation.
   void registerNoSuchMethod(MethodElement noSuchMethod) {
     noSuchMethodRegistry.registerNoSuchMethod(noSuchMethod);
   }
 
   /// Called when resolving a call to a foreign function.
@@ skipping 27 matching lines @@
           node, MessageKind.WRONG_ARGUMENT_FOR_JS_INTERCEPTOR_CONSTANT);
     }
     // No native behavior for this call.
     return null;
   }
 
   WorldImpact computeNoSuchMethodImpact() {
     return impactTransformer.createImpactFor(impacts.noSuchMethodSupport);
   }
 
+  /// Called to enable support for isolates. Any backend specific [WorldImpact]
+  /// of this is returned.
   WorldImpact enableIsolateSupport({bool forResolution}) {
     WorldImpactBuilderImpl impactBuilder = new WorldImpactBuilderImpl();
     // TODO(floitsch): We should also ensure that the class IsolateMessage is
     // instantiated. Currently, just enabling isolate support works.
     if (compiler.mainFunction != null) {
       // The JavaScript backend implements [Isolate.spawn] by looking up
       // top-level functions by name. So all top-level function tear-off
       // closures have a private name field.
       //
       // The JavaScript backend of [Isolate.spawnUri] uses the same internal
@@ skipping 24 matching lines @@
 
   bool isComplexNoSuchMethod(FunctionElement element) =>
       noSuchMethodRegistry.isComplex(element);
 
   bool methodNeedsRti(FunctionElement function) {
     return rti.methodsNeedingRti.contains(function) || hasRuntimeTypeSupport;
   }
 
   CodegenEnqueuer get codegenEnqueuer => compiler.enqueuer.codegen;
 
+  /// Creates an [Enqueuer] for code generation specific to this backend.
   CodegenEnqueuer createCodegenEnqueuer(CompilerTask task, Compiler compiler) {
     return new CodegenEnqueuer(
         task, this, compiler.options, const TreeShakingEnqueuerStrategy());
   }
 
   WorldImpact codegen(CodegenWorkItem work) {
     Element element = work.element;
     if (compiler.elementHasCompileTimeError(element)) {
       DiagnosticMessage message =
           // If there's more than one error, the first is probably most
@@ skipping 84 matching lines @@
   /**
    * Unit test hook that returns code of an element as a String.
    *
    * Invariant: [element] must be a declaration element.
    */
   String getGeneratedCode(Element element) {
     assert(invariant(element, element.isDeclaration));
     return jsAst.prettyPrint(generatedCode[element], compiler);
   }
 
+  /// Generates the output and returns the total size of the generated code.
   int assembleProgram(ClosedWorld closedWorld) {
     int programSize = emitter.assembleProgram(namer, closedWorld);
     noSuchMethodRegistry.emitDiagnostic();
     int totalMethodCount = generatedCode.length;
     if (totalMethodCount != preMirrorsMethodCount) {
       int mirrorCount = totalMethodCount - preMirrorsMethodCount;
       double percentage = (mirrorCount / totalMethodCount) * 100;
       DiagnosticMessage hint =
           reporter.createMessage(compiler.mainApp, MessageKind.MIRROR_BLOAT, {
         'count': mirrorCount,
@@ skipping 201 matching lines @@
   bool mayGenerateInstanceofCheck(ResolutionDartType type) {
     // We can use an instanceof check for raw types that have no subclass that
     // is mixed-in or in an implements clause.
 
     if (!type.isRaw) return false;
     ClassElement classElement = type.element;
     if (isInterceptorClass(classElement)) return false;
     return _closedWorld.hasOnlySubclasses(classElement);
   }
 
+  /// Called to register that [element] is statically known to be used. Any
+  /// backend specific [WorldImpact] of this is returned.
   WorldImpact registerUsedElement(MemberElement element, {bool forResolution}) {
     WorldImpactBuilderImpl worldImpact = new WorldImpactBuilderImpl();
     if (element == helpers.disableTreeShakingMarker) {
       isTreeShakingDisabled = true;
     } else if (element == helpers.preserveNamesMarker) {
       mustPreserveNames = true;
     } else if (element == helpers.preserveMetadataMarker) {
       mustRetainMetadata = true;
     } else if (element == helpers.preserveUrisMarker) {
       if (compiler.options.preserveUris) mustPreserveUris = true;
@@ skipping 103 matching lines @@
         metadata.ensureResolved(resolution);
         ConstantValue constant =
             constants.getConstantValueForMetadata(metadata);
         constants.addCompileTimeConstantForEmission(constant);
       }
       return true;
     }
     return false;
   }
 
+  /// This method is called immediately after the [library] and its parts have
+  /// been scanned.
   Future onLibraryScanned(LibraryElement library, LibraryLoader loader) {
-    return super.onLibraryScanned(library, loader).then((_) {
-      if (library.isPlatformLibrary &&
-          // Don't patch library currently disallowed.
-          !library.isSynthesized &&
-          !library.isPatched &&
-          // Don't patch deserialized libraries.
-          !compiler.serialization.isDeserialized(library)) {
-        // Apply patch, if any.
-        Uri patchUri = compiler.resolvePatchUri(library.canonicalUri.path);
-        if (patchUri != null) {
-          return compiler.patchParser.patchLibrary(loader, patchUri, library);
+    // TODO(johnniwinther): Move this to [JavaScriptBackend].

[Siggi Cherem (dart-lang), 2017/02/08 00:10:03]

remove TODO?

[Johnni Winther, 2017/02/08 09:46:35]

Done.

+    if (!compiler.serialization.isDeserialized(library)) {
+      if (canLibraryUseNative(library)) {
+        library.forEachLocalMember((Element element) {
+          if (element.isClass) {
+            checkNativeAnnotation(compiler, element);
+          }
+        });
+      }
+      checkJsInteropAnnotation(compiler, library);
+      library.forEachLocalMember((Element element) {
+        checkJsInteropAnnotation(compiler, element);
+        if (element.isClass && isJsInterop(element)) {
+          ClassElement classElement = element;
+          classElement.forEachMember((_, memberElement) {
+            checkJsInteropAnnotation(compiler, memberElement);
+          });
         }
+      });
+    }
+    if (library.isPlatformLibrary &&
+        // Don't patch library currently disallowed.
+        !library.isSynthesized &&
+        !library.isPatched &&
+        // Don't patch deserialized libraries.
+        !compiler.serialization.isDeserialized(library)) {
+      // Apply patch, if any.
+      Uri patchUri = compiler.resolvePatchUri(library.canonicalUri.path);
+      if (patchUri != null) {
+        return compiler.patchParser.patchLibrary(loader, patchUri, library);
       }
-    }).then((_) {
-      Uri uri = library.canonicalUri;
-      if (uri == Uris.dart_html) {
-        htmlLibraryIsLoaded = true;
-      } else if (uri == LookupMapAnalysis.PACKAGE_LOOKUP_MAP) {
-        lookupMapAnalysis.init(library);
-      }
-      annotations.onLibraryScanned(library);
-    });
+    }
+    Uri uri = library.canonicalUri;
+    if (uri == Uris.dart_html) {
+      htmlLibraryIsLoaded = true;
+    } else if (uri == LookupMapAnalysis.PACKAGE_LOOKUP_MAP) {
+      lookupMapAnalysis.init(library);
+    }
+    annotations.onLibraryScanned(library);
+    return new Future.value();
   }
 
+  /// This method is called when all new libraries loaded through
+  /// [LibraryLoader.loadLibrary] has been loaded and their imports/exports
+  /// have been computed.
   Future onLibrariesLoaded(LoadedLibraries loadedLibraries) {
     if (!loadedLibraries.containsLibrary(Uris.dart_core)) {
       return new Future.value();
     }
 
     helpers.onLibrariesLoaded(loadedLibraries);
 
     implementationClasses = <ClassElement, ClassElement>{};
     implementationClasses[commonElements.intClass] = helpers.jsIntClass;
     implementationClasses[commonElements.boolClass] = helpers.jsBoolClass;
@@ skipping 12 matching lines @@
       ..add(helpers.jsInterceptorClass)
       ..add(helpers.jsNullClass);
 
     validateInterceptorImplementsAllObjectMethods(helpers.jsInterceptorClass);
     // The null-interceptor must also implement *all* methods.
     validateInterceptorImplementsAllObjectMethods(helpers.jsNullClass);
 
     return new Future.value();
   }
 
+  /// Called by [MirrorUsageAnalyzerTask] after it has merged all @MirrorsUsed
+  /// annotations. The arguments corresponds to the unions of the corresponding
+  /// fields of the annotations.
   void registerMirrorUsage(
       Set<String> symbols, Set<Element> targets, Set<Element> metaTargets) {
     if (symbols == null && targets == null && metaTargets == null) {
       // The user didn't specify anything, or there are imports of
       // 'dart:mirrors' without @MirrorsUsed.
       hasInsufficientMirrorsUsed = true;
       return;
     }
     if (symbols != null) symbolsUsed.addAll(symbols);
     if (targets != null) {
@@ skipping 19 matching lines @@
    * accessed (invoked, get, set) that is not accessible for the reflective
    * system.
    */
   bool isAccessibleByReflection(Element element) {
     if (element.isClass) {
       element = getDartClass(element);
     }
     return membersNeededForReflection.contains(element);
   }
 
+  /// Returns `true` if this member element needs reflection information at
+  /// runtime.
   bool isMemberAccessibleByReflection(MemberElement element) {
     return membersNeededForReflection.contains(element);
   }
 
-  /**
-   * Returns true if the element has to be resolved due to a mirrorsUsed
-   * annotation. If we have insufficient mirrors used annotations, we only
-   * keep additional elements if treeshaking has been disabled.
-   */
+  /// Returns true if this element has to be enqueued due to
+  /// mirror usage. Might be a subset of [referencedFromMirrorSystem] if
+  /// normal tree shaking is still active ([isTreeShakingDisabled] is false).
   bool requiredByMirrorSystem(Element element) {
     return hasInsufficientMirrorsUsed && isTreeShakingDisabled ||
         matchesMirrorsMetaTarget(element) ||
         targetsUsed.contains(element);
   }
 
-  /**
-   * Returns true if the element matches a mirrorsUsed annotation. If
-   * we have insufficient mirrorsUsed information, this returns true for
-   * all elements, as they might all be potentially referenced.
-   */
+  /// Returns true if this element is covered by a mirrorsUsed annotation.
+  ///
+  /// Note that it might still be ok to tree shake the element away if no
+  /// reflection is used in the program (and thus [isTreeShakingDisabled] is
+  /// still false). Therefore _do not_ use this predicate to decide inclusion
+  /// in the tree, use [requiredByMirrorSystem] instead.
   bool referencedFromMirrorSystem(Element element, [recursive = true]) {
     Element enclosing = recursive ? element.enclosingElement : null;
 
     return hasInsufficientMirrorsUsed ||
         matchesMirrorsMetaTarget(element) ||
         targetsUsed.contains(element) ||
         (enclosing != null && referencedFromMirrorSystem(enclosing));
   }
 
   /**
@@ skipping 216 matching lines @@
       if (target == null) continue;
       if (target.isField) {
         staticFields.add(target);
       } else if (target.isLibrary || target.isClass) {
         addFieldsInContainer(target);
       }
     }
     return staticFields;
   }
 
-  /// Called when [enqueuer] is empty, but before it is closed.
+  /// Called when [enqueuer]'s queue is empty, but before it is closed.
+  ///
+  /// This is used, for example, by the JS backend to enqueue additional
+  /// elements needed for reflection. [recentClasses] is a collection of
+  /// all classes seen for the first time by the [enqueuer] since the last call
+  /// to [onQueueEmpty].
+  ///
+  /// A return value of [:true:] indicates that [recentClasses] has been
+  /// processed and its elements do not need to be seen in the next round. When
+  /// [:false:] is returned, [onQueueEmpty] will be called again once the
+  /// resolution queue has drained and [recentClasses] will be a superset of the
+  /// current value.
+  ///
+  /// There is no guarantee that a class is only present once in
+  /// [recentClasses], but every class seen by the [enqueuer] will be present in
+  /// [recentClasses] at least once.
   bool onQueueEmpty(Enqueuer enqueuer, Iterable<ClassEntity> recentClasses) {
     // Add elements used synthetically, that is, through features rather than
     // syntax, for instance custom elements.
     //
     // Return early if any elements are added to avoid counting the elements as
     // due to mirrors.
     enqueuer.applyImpact(customElementsAnalysis.flush(
         forResolution: enqueuer.isResolutionQueue));
     enqueuer.applyImpact(
         lookupMapAnalysis.flush(forResolution: enqueuer.isResolutionQueue));
@@ skipping 120 matching lines @@
           }
         } else {
           processLibraryMetadata(element.library);
         }
       }
     }
 
     entities.forEach(processElementMetadata);
   }
 
+  /// Called after the queue is closed. [onQueueEmpty] may be called multiple
+  /// times, but [onQueueClosed] is only called once.
   void onQueueClosed() {
     lookupMapAnalysis.onQueueClosed();
     jsInteropAnalysis.onQueueClosed();
   }
 
   // TODO(johnniwinther): Create a CodegenPhase object for the backend to hold
   // data only available during code generation.
   ClosedWorld _closedWorldCache;
   ClosedWorld get _closedWorld {
     assert(invariant(NO_LOCATION_SPANNABLE, _closedWorldCache != null,
         message: "ClosedWorld has not be set yet."));
     return _closedWorldCache;
   }
 
   void set _closedWorld(ClosedWorld value) {
     _closedWorldCache = value;
   }
 
+  /// Called when the compiler starts running the codegen enqueuer. The
+  /// [WorldImpact] of enabled backend features is returned.
   WorldImpact onCodegenStart(ClosedWorld closedWorld) {
     _closedWorld = closedWorld;
     _namer = determineNamer(_closedWorld, compiler.codegenWorldBuilder);
     tracer = new Tracer(_closedWorld, namer, compiler.outputProvider);
     emitter.createEmitter(_namer, _closedWorld);
     lookupMapAnalysis.onCodegenStart();
     if (hasIsolateSupport) {
       return enableIsolateSupport(forResolution: false);
     }
     return const WorldImpact();
   }
 
+  /// Called when code generation has been completed.
   void onCodegenEnd() {
     sourceInformationStrategy.onComplete();
     tracer.close();
   }
 
+  // Does this element belong in the output
+  bool shouldOutput(Element element) => true;
+
+  /// Returns `true` if the `native` pseudo keyword is supported for [library].
+  bool canLibraryUseNative(LibraryElement library) {
+    return native.maybeEnableNative(compiler, library);
+  }
+
+  @override
+  bool isTargetSpecificLibrary(LibraryElement library) {
+    Uri canonicalUri = library.canonicalUri;
+    if (canonicalUri == BackendHelpers.DART_JS_HELPER ||
+        canonicalUri == BackendHelpers.DART_INTERCEPTORS) {
+      return true;
+    }
+    return false;
+  }
+
   /// Process backend specific annotations.
   void processAnnotations(
       Element element, ClosedWorldRefiner closedWorldRefiner) {
     if (element.isMalformed) {
       // Elements that are marked as malformed during parsing or resolution
       // might be registered here. These should just be ignored.
       return;
     }
 
     Element implementation = element.implementation;
@@ skipping 66 matching lines @@
           "@NoSideEffects() should always be combined with @NoInline.");
     }
   }
 
   MethodElement helperForBadMain() => helpers.badMain;
 
   MethodElement helperForMissingMain() => helpers.missingMain;
 
   MethodElement helperForMainArity() => helpers.mainHasTooManyParameters;
 
-  @override
+  /// Computes the [WorldImpact] of calling [mainMethod] as the entry point.
   WorldImpact computeMainImpact(MethodElement mainMethod,
       {bool forResolution}) {
     WorldImpactBuilderImpl mainImpact = new WorldImpactBuilderImpl();
     if (mainMethod.parameters.isNotEmpty) {
       impactTransformer.registerBackendImpact(
           mainImpact, impacts.mainWithArguments);
       mainImpact.registerStaticUse(
           new StaticUse.staticInvoke(mainMethod, CallStructure.TWO_ARGS));
       // If the main method takes arguments, this compilation could be the
       // target of Isolate.spawnUri. Strictly speaking, that can happen also if
@@ skipping 13 matching lines @@
   String deferredPartFileName(String name, {bool addExtension: true}) {
     assert(name != "");
     String outPath = compiler.options.outputUri != null
         ? compiler.options.outputUri.path
         : "out";
     String outName = outPath.substring(outPath.lastIndexOf('/') + 1);
     String extension = addExtension ? ".part.js" : "";
     return "${outName}_$name$extension";
   }
 
-  @override
+  /// Enable deferred loading. Returns `true` if the backend supports deferred
+  /// loading.
   bool enableDeferredLoadingIfSupported(Spannable node) => true;
 
-  @override
+  /// Enable compilation of code with compile time errors. Returns `true` if
+  /// supported by the backend.
   bool enableCodegenWithErrorsIfSupported(Spannable node) => true;
 
   jsAst.Expression rewriteAsync(
       FunctionElement element, jsAst.Expression code) {
     AsyncRewriterBase rewriter = null;
     jsAst.Name name = namer.methodPropertyName(element);
     switch (element.asyncMarker) {
       case AsyncMarker.ASYNC:
         rewriter = new AsyncRewriter(reporter, element,
             asyncHelper: emitter.staticFunctionAccess(helpers.asyncHelper),
@@ skipping 46 matching lines @@
     "core": "_internal/js_runtime/lib/core_patch.dart",
     "developer": "_internal/js_runtime/lib/developer_patch.dart",
     "io": "_internal/js_runtime/lib/io_patch.dart",
     "isolate": "_internal/js_runtime/lib/isolate_patch.dart",
     "math": "_internal/js_runtime/lib/math_patch.dart",
     "mirrors": "_internal/js_runtime/lib/mirrors_patch.dart",
     "typed_data": "_internal/js_runtime/lib/typed_data_patch.dart",
     "_internal": "_internal/js_runtime/lib/internal_patch.dart"
   };
 
-  @override
+  /// Returns the location of the patch-file associated with [libraryName]
+  /// resolved from [plaformConfigUri].
+  ///
+  /// Returns null if there is none.
   Uri resolvePatchUri(String libraryName, Uri platformConfigUri) {
     String patchLocation = _patchLocations[libraryName];
     if (patchLocation == null) return null;
     return platformConfigUri.resolve(patchLocation);
   }
 
-  @override
+  /// Creates an impact strategy to use for compilation.
   ImpactStrategy createImpactStrategy(
       {bool supportDeferredLoad: true,
       bool supportDumpInfo: true,
       bool supportSerialization: true}) {
     return new JavaScriptImpactStrategy(resolution, compiler.dumpInfoTask,
         supportDeferredLoad: supportDeferredLoad,
         supportDumpInfo: supportDumpInfo,
         supportSerialization: supportSerialization);
   }
+
+  EnqueueTask makeEnqueuer() => new EnqueueTask(compiler);
 }
 
 class JSFrontendAccess implements Frontend {
   final Compiler compiler;
 
   JSFrontendAccess(this.compiler);
 
   Resolution get resolution => compiler.resolution;
 
   @override
@@ skipping 641 matching lines @@
   @override
   bool isNativeClass(ClassElement element) {
     return helpers.backend.isNative(element);
   }
 
   @override
   bool isNativeMember(MemberElement element) {
     return helpers.backend.isNative(element);
   }
 }