dart2js: More documentation for embedded globals and properties.

sdk/lib/_internal/js_runtime/lib/shared/embedded_names.dart

Index: sdk/lib/_internal/js_runtime/lib/shared/embedded_names.dart
diff --git a/sdk/lib/_internal/js_runtime/lib/shared/embedded_names.dart b/sdk/lib/_internal/js_runtime/lib/shared/embedded_names.dart
index 8e11da34fd44553388c53d9d5a48c826fa819a79..a42799688da32ec9f858d9a6ebd2c32ba2efec98 100644
--- a/sdk/lib/_internal/js_runtime/lib/shared/embedded_names.dart
+++ b/sdk/lib/_internal/js_runtime/lib/shared/embedded_names.dart
@@ -11,10 +11,58 @@
 /// This library is shared between the compiler and the runtime system.
 library dart2js._embedded_names;
 
-const DISPATCH_PROPERTY_NAME = "dispatchPropertyName";
-const TYPE_INFORMATION = 'typeInformation';
+/// The name of the property that is used to mark a type as typedef.
+///
+/// Without reflection typedefs are removed (expanded to their function type)
+/// but with reflection an object is needed to have the typedef's name. The
+/// object is marked with this property.
+///
+/// This property name only lives on internal type-objects and is only used
+/// when reflection is enabled.
+const TYPEDEF_PREDICATE_PROPERTY_NAME = r"$$isTypedef";
+
+/// The name of the property that is used to find the function type of a
+/// typedef.
+///
+/// Without reflection typedefs are removed (expanded to their function type)
+/// but with reflection an object is needed to have the typedef's name.
+///
+/// The typedef's object contains a pointer to its function type (as an index
+/// into the embedded global [TYPES]) in this property.
+///
+/// This property name only lives on internal type-objects and is only used
+/// when reflection is enabled.
+const TYPEDEF_TYPE_PROPERTY_NAME = r"$typedefType";
+
+/// The name of the property that is used to find the native superclass of
+/// an extended class.
+///
+/// Every class that extends a native class has this property set on its
+/// native class.
+const NATIVE_SUPERCLASS_TAG_NAME = r"$nativeSuperclassTag";
+
+
+/// The name of the embedded global for metadata.
+///
+/// Use [JsBuiltin.getMetadata] instead of directly accessing this embedded
+/// global.
+const METADATA = 'metadata';
+
+/// A list of types used in the program e.g. for reflection or encoding of
+/// function types.
+///
+/// Use [JsBuiltin.getType] instead of directly accessing this embedded global.
+const TYPES = 'types';
+
+/// An embedded global name that can be used to store a mapping from
+/// static function names to dart-closure getters.
 const GLOBAL_FUNCTIONS = 'globalFunctions';
-const STATICS = 'statics';
+
+/// Returns a function that maps a name of a class to its type.
+///
+/// This embedded global is used by the runtime when computing the internal
+/// runtime-type-information (rti) object.
+const GET_TYPE_FROM_NAME = 'getTypeFromName';
 
 /// If [JSInvocationMirror._invokeOn] is being used, this embedded global
 /// contains a JavaScript map with the names of methods that are
@@ -23,58 +71,204 @@ const INTERCEPTED_NAMES = 'interceptedNames';
 
 /// A JS map from mangled global names to their unmangled names.
 ///
-/// If the program does not use reflection may be empty (but not null or
-/// undefined).
+/// If the program does not use reflection, this embedded global may be empty
+/// (but not null or undefined).
 const MANGLED_GLOBAL_NAMES = 'mangledGlobalNames';
 
+/// A JS map from mangled instance names to their unmangled names.
+///
+/// If the program does not use reflection, this embedded global may be empty
+/// (but not null or undefined).
 const MANGLED_NAMES = 'mangledNames';
-const LIBRARIES = 'libraries';
-const FINISHED_CLASSES = 'finishedClasses';
-const ALL_CLASSES = 'allClasses';
+
+/// A JS map from dispatch tags (usually constructor names of DOM classes) to
+/// interceptor class. This map is used to find the correct interceptor for
+/// native classes.
+///
+/// This embedded global is used for natives.
 const INTERCEPTORS_BY_TAG = 'interceptorsByTag';
+
+/// A JS map from dispatch tags (usually constructor names of DOM classes) to
+/// booleans. Every tag entry of [INTERCEPTORS_BY_TAG] has a corresponding
+/// entry in the leaf-tags map.
+///
+/// A tag-entry is true, when a class can be treated as leaf class in the
+/// hierarchy. That is, even though it might have subclasses, all subclasses
+/// have the same code for the used methods.
+///
+/// This embedded global is used for natives.
 const LEAF_TAGS = 'leafTags';
-const LAZIES = 'lazies';
+
+/// A JS function that returns the isolate tag for a given name.
+///
+/// This function uses the [ISOLATE_TAG] (below) to construct a name that is
+/// unique per isolate.
+///
+/// This embedded global is used for natives.
+// TODO(floitsch): should we rename this variable to avoid confusion with
+//    [INTERCEPTORS_BY_TAG] and [LEAF_TAGS].
 const GET_ISOLATE_TAG = 'getIsolateTag';
+
+/// A string that is different for each running isolate.
+///
+/// When this embedded global is initialized a global variable is used to
+/// ensure that no other running isolate uses the same isolate-tag string.
+///
+/// This embedded global is used for natives.
+// TODO(floitsch): should we rename this variable to avoid confusion with
+//    [INTERCEPTORS_BY_TAG] and [LEAF_TAGS].
 const ISOLATE_TAG = 'isolateTag';
+
+/// This embedded global (a function) returns the isolate-specific dispatch-tag
+/// that is used to accelerate interceptor calls.
+const DISPATCH_PROPERTY_NAME = "dispatchPropertyName";
+
+/// An embedded global that maps a [Type] to the [Interceptor] and constructors
+/// for that type.
+///
+/// More documentation can be found in the interceptors library (close to its
+/// use).
+const TYPE_TO_INTERCEPTOR_MAP = "typeToInterceptorMap";
+
+/// The current script's URI when the program was loaded.
+///
+/// This embedded global is set at startup, just before invoking `main`.
 const CURRENT_SCRIPT = 'currentScript';
+
+/// Returns a function that creates a new Isolate (its static state).
+///
+/// (floitsch): Note that this embedded global will probably go away, since one
+/// JS heap will only contain one Dart isolate.
+const CREATE_NEW_ISOLATE = 'createNewIsolate';
+
+/// Returns a class-id of the given instance.
+///
+/// The extracted id can be used to built a new instance of the same type
+/// (see [INSTANCE_FROM_CLASS_ID].
+///
+/// This embedded global is used for serialization in the isolate-library.
+const CLASS_ID_EXTRACTOR = 'classIdExtractor';
+
+/// Returns an empty instance of the given class-id.
+///
+/// Given a class-id (see [CLASS_ID_EXTRACTOR]) returns an empty instance.
+///
+/// This embedded global is used for deserialization in the isolate-library.
+const INSTANCE_FROM_CLASS_ID = "instanceFromClassId";
+
+/// Returns a list of (mangled) field names for the given instance.
+///
+/// The list of fields can be used to extract the instance's values and then
+/// initialize an empty instance (see [INITIALIZE_EMPTY_INSTANCE].
+///
+/// This embedded global is used for serialization in the isolate-library.
+const CLASS_FIELDS_EXTRACTOR = 'classFieldsExtractor';
+
+/// Initializes the given empty instance with the given fields.
+///
+/// The given fields are in an array and must be in the same order as the
+/// field-names obtained by [CLASS_FIELDS_EXTRACTOR].
+///
+/// This embedded global is used for deserialization in the isolate-library.
+const INITIALIZE_EMPTY_INSTANCE = "initializeEmptyInstance";
+
+/// Returns a map from load-ids to URIs.
+///
+/// To load the deferred library that is represented by the load-id, the runtime
+/// must load all associated URIs.
+///
+/// This embedded global is only used for deferred loading.
 const DEFERRED_LIBRARY_URIS = 'deferredLibraryUris';
+
+/// Returns a map from load-ids to hashes.
+///
+/// The hashes are associated with the URIs of the load-ids (see
+/// [DEFERRED_LIBRARY_URIS]). They are MD5 (or similar) hashes of the code that
+/// must be loaded. By using cryptographic hashes we can avoid loading similar
+/// code multiple times.
+///
+/// This embedded global is only used for deferred loading.
 const DEFERRED_LIBRARY_HASHES = 'deferredLibraryHashes';
+
+/// Initialize a loaded hunk.
+///
+/// Once a hunk (the code from a deferred URI) has been loaded it must be
+/// initialized. Calling this function with the corresponding hash (see
+/// [DEFERRED_LIBRARY_HASHES]) initializes the code.
+///
+/// This embedded global is only used for deferred loading.
 const INITIALIZE_LOADED_HUNK = 'initializeLoadedHunk';
+
+/// Returns, whether a hunk (identified by its hash) has already been loaded.
+///
+/// This embedded global is only used for deferred loading.
 const IS_HUNK_LOADED = 'isHunkLoaded';
+
+/// Returns, whether a hunk (identified by its hash) has already been
+/// initialized.
+///
+/// This embedded global is only used for deferred loading.
 const IS_HUNK_INITIALIZED = 'isHunkInitialized';
+
+/// A set (implemented as map to booleans) of hunks (identified by hashes) that
+/// have already been initialized.
+///
+/// This embedded global is only used for deferred loading.
+///
+/// This global is an emitter-internal embedded global, and not used by the
+/// runtime. The constant remains in this file to make sure that other embedded
+/// globals don't clash with it.
 const DEFERRED_INITIALIZED = 'deferredInitialized';
+
+
+/// Returns a function that creates all precompiled functions (in particular
+/// constructors).
+///
+/// That is, the function returns the array that the full emitter would
+/// otherwise build dynamically when it finishes all classes.
+///
+/// This constant is only used in CSP mode.
+///
+/// This global is an emitter-internal embedded global, and not used by the
+/// runtime. The constant remains in this file to make sure that other embedded
+/// globals don't clash with it.
 const PRECOMPILED = 'precompiled';
 
-/// The name of the embedded global for metadata.
+/// An emitter-internal embedded global. This global is not used by the runtime.
 ///
-/// Use [JsBuiltin.getMetadata] instead of directly accessing this embedded
-/// global.
-const METADATA = 'metadata';
+/// The constant remains in this file to make sure that other embedded globals
+/// don't clash with it.
+const FINISHED_CLASSES = 'finishedClasses';
 
-/// A list of types used in the program e.g. for reflection or encoding of
-/// function types.
+
+/// A JavaScript object literal that maps the (minified) JavaScript constructor
+/// name (as given by [JsBuiltin.rawRtiToJsConstructorName] to the
+/// JavaScript constructor.
 ///
-/// Use [JsBuiltin.getType] instead of directly accessing this embedded global.
-const TYPES = 'types';
+/// This embedded global is only used by reflection.
+const ALL_CLASSES = 'allClasses';
 
-/// Returns a function that creates a new Isolate (its static state).
+/// A map from element to type information.
 ///
-/// (floitsch): Note that this will probably go away, since one JS heap will
-/// only contain one Dart isolate.
-const CREATE_NEW_ISOLATE = 'createNewIsolate';
+/// This embedded global is only used by reflection.
+const TYPE_INFORMATION = 'typeInformation';
 
-const CLASS_ID_EXTRACTOR = 'classIdExtractor';
-const CLASS_FIELDS_EXTRACTOR = 'classFieldsExtractor';
-const INSTANCE_FROM_CLASS_ID = "instanceFromClassId";
-const INITIALIZE_EMPTY_INSTANCE = "initializeEmptyInstance";
-const TYPEDEF_TYPE_PROPERTY_NAME = r"$typedefType";
-const TYPEDEF_PREDICATE_PROPERTY_NAME = r"$$isTypedef";
-const NATIVE_SUPERCLASS_TAG_NAME = r"$nativeSuperclassTag";
+/// A map from statics to their descriptors.
+///
+/// This embedded global is only used by reflection.
+const STATICS = 'statics';
 
-/// Returns the type given the name of a class.
-/// This function is called by the runtime when computing rti.
-const GET_TYPE_FROM_NAME = 'getTypeFromName';
-const TYPE_TO_INTERCEPTOR_MAP = "typeToInterceptorMap";
+/// An array of library descriptors.
+///
+/// The descriptor contains information such as name, uri, classes, ...
+///
+/// This embedded global is only used by reflection.
+const LIBRARIES = 'libraries';
+
+/// A map from lazy statics to their initializers.
+///
+/// This embedded global is only used by reflection.
+const LAZIES = 'lazies';
 
 /// Names that are supported by [JS_GET_NAME].
 // TODO(herhut): Make entries lower case (as in fields) and find a better name.