From ed4b205b47ede3b502873a552a976aadd0f6619f Mon Sep 17 00:00:00 2001 From: Michael Wu Date: Sat, 17 Oct 2015 13:27:16 -0400 Subject: [PATCH] Bug 1212663 - Use doxygen style comments in jsapi, r=Waldo --- js/public/Class.h | 229 ++++++++------- js/public/Conversions.h | 4 +- js/public/GCAPI.h | 58 ++-- js/public/HeapAPI.h | 14 +- js/public/Id.h | 2 +- js/public/MemoryMetrics.h | 95 ++++--- js/public/RootingAPI.h | 26 +- js/public/StructuredClone.h | 153 +++++----- js/public/TracingAPI.h | 36 ++- js/public/Value.h | 79 ++++-- js/src/jsapi.h | 544 +++++++++++++++++++----------------- js/src/jsfriendapi.h | 304 +++++++++++--------- 12 files changed, 856 insertions(+), 688 deletions(-) diff --git a/js/public/Class.h b/js/public/Class.h index 31c13dbd5823..21309506ea71 100644 --- a/js/public/Class.h +++ b/js/public/Class.h @@ -46,8 +46,10 @@ template class AutoVectorRooter; typedef AutoVectorRooter AutoIdVector; -// The answer to a successful query as to whether an object is an Array per -// ES6's internal |IsArray| operation (as exposed by |Array.isArray|). +/** + * The answer to a successful query as to whether an object is an Array per + * ES6's internal |IsArray| operation (as exposed by |Array.isArray|). + */ enum class IsArrayAnswer { Array, @@ -55,29 +57,33 @@ enum class IsArrayAnswer RevokedProxy }; -// ES6 7.2.2. -// -// Returns false on failure, otherwise returns true and sets |*isArray| -// indicating whether the object passes ECMAScript's IsArray test. This is the -// same test performed by |Array.isArray|. -// -// This is NOT the same as asking whether |obj| is an Array or a wrapper around -// one. If |obj| is a proxy created by |Proxy.revocable()| and has been -// revoked, or if |obj| is a proxy whose target (at any number of hops) is a -// revoked proxy, this method throws a TypeError and returns false. +/** + * ES6 7.2.2. + * + * Returns false on failure, otherwise returns true and sets |*isArray| + * indicating whether the object passes ECMAScript's IsArray test. This is the + * same test performed by |Array.isArray|. + * + * This is NOT the same as asking whether |obj| is an Array or a wrapper around + * one. If |obj| is a proxy created by |Proxy.revocable()| and has been + * revoked, or if |obj| is a proxy whose target (at any number of hops) is a + * revoked proxy, this method throws a TypeError and returns false. + */ extern JS_PUBLIC_API(bool) IsArray(JSContext* cx, HandleObject obj, bool* isArray); -// Identical to IsArray above, but the nature of the object (if successfully -// determined) is communicated via |*answer|. In particular this method -// returns true and sets |*answer = IsArrayAnswer::RevokedProxy| when called on -// a revoked proxy. -// -// Most users will want the overload above, not this one. +/** + * Identical to IsArray above, but the nature of the object (if successfully + * determined) is communicated via |*answer|. In particular this method + * returns true and sets |*answer = IsArrayAnswer::RevokedProxy| when called on + * a revoked proxy. + * + * Most users will want the overload above, not this one. + */ extern JS_PUBLIC_API(bool) IsArray(JSContext* cx, HandleObject obj, IsArrayAnswer* answer); -/* +/** * Per ES6, the [[DefineOwnProperty]] internal method has three different * possible outcomes: * @@ -113,7 +119,7 @@ IsArray(JSContext* cx, HandleObject obj, IsArrayAnswer* answer); class ObjectOpResult { private: - /* + /** * code_ is either one of the special codes OkCode or Uninitialized, or * an error code. For now the error codes are private to the JS engine; * they're defined in js/src/js.msg. @@ -249,117 +255,136 @@ class ObjectOpResult // JSClass operation signatures. -// Get a property named by id in obj. Note the jsid id type -- id may -// be a string (Unicode property identifier) or an int (element index). The -// *vp out parameter, on success, is the new property value after the action. +/** + * Get a property named by id in obj. Note the jsid id type -- id may + * be a string (Unicode property identifier) or an int (element index). The + * *vp out parameter, on success, is the new property value after the action. + */ typedef bool (* JSGetterOp)(JSContext* cx, JS::HandleObject obj, JS::HandleId id, JS::MutableHandleValue vp); -// Add a property named by id to obj. +/** Add a property named by id to obj. */ typedef bool (* JSAddPropertyOp)(JSContext* cx, JS::HandleObject obj, JS::HandleId id, JS::HandleValue v); -// Set a property named by id in obj, treating the assignment as strict -// mode code if strict is true. Note the jsid id type -- id may be a string -// (Unicode property identifier) or an int (element index). The *vp out -// parameter, on success, is the new property value after the -// set. +/** + * Set a property named by id in obj, treating the assignment as strict + * mode code if strict is true. Note the jsid id type -- id may be a string + * (Unicode property identifier) or an int (element index). The *vp out + * parameter, on success, is the new property value after the + * set. + */ typedef bool (* JSSetterOp)(JSContext* cx, JS::HandleObject obj, JS::HandleId id, JS::MutableHandleValue vp, JS::ObjectOpResult& result); -// Delete a property named by id in obj. -// -// If an error occurred, return false as per normal JSAPI error practice. -// -// If no error occurred, but the deletion attempt wasn't allowed (perhaps -// because the property was non-configurable), call result.fail() and -// return true. This will cause |delete obj[id]| to evaluate to false in -// non-strict mode code, and to throw a TypeError in strict mode code. -// -// If no error occurred and the deletion wasn't disallowed (this is *not* the -// same as saying that a deletion actually occurred -- deleting a non-existent -// property, or an inherited property, is allowed -- it's just pointless), -// call result.succeed() and return true. +/** + * Delete a property named by id in obj. + * + * If an error occurred, return false as per normal JSAPI error practice. + * + * If no error occurred, but the deletion attempt wasn't allowed (perhaps + * because the property was non-configurable), call result.fail() and + * return true. This will cause |delete obj[id]| to evaluate to false in + * non-strict mode code, and to throw a TypeError in strict mode code. + * + * If no error occurred and the deletion wasn't disallowed (this is *not* the + * same as saying that a deletion actually occurred -- deleting a non-existent + * property, or an inherited property, is allowed -- it's just pointless), + * call result.succeed() and return true. + */ typedef bool (* JSDeletePropertyOp)(JSContext* cx, JS::HandleObject obj, JS::HandleId id, JS::ObjectOpResult& result); -// The type of ObjectOps::enumerate. This callback overrides a portion of -// SpiderMonkey's default [[Enumerate]] internal method. When an ordinary object -// is enumerated, that object and each object on its prototype chain is tested -// for an enumerate op, and those ops are called in order. The properties each -// op adds to the 'properties' vector are added to the set of values the for-in -// loop will iterate over. All of this is nonstandard. -// -// An object is "enumerated" when it's the target of a for-in loop or -// JS_Enumerate(). The callback's job is to populate 'properties' with the -// object's property keys. If `enumerableOnly` is true, the callback should only -// add enumerable properties. +/** + * The type of ObjectOps::enumerate. This callback overrides a portion of + * SpiderMonkey's default [[Enumerate]] internal method. When an ordinary object + * is enumerated, that object and each object on its prototype chain is tested + * for an enumerate op, and those ops are called in order. The properties each + * op adds to the 'properties' vector are added to the set of values the for-in + * loop will iterate over. All of this is nonstandard. + * + * An object is "enumerated" when it's the target of a for-in loop or + * JS_Enumerate(). The callback's job is to populate 'properties' with the + * object's property keys. If `enumerableOnly` is true, the callback should only + * add enumerable properties. + */ typedef bool (* JSNewEnumerateOp)(JSContext* cx, JS::HandleObject obj, JS::AutoIdVector& properties, bool enumerableOnly); -// The old-style JSClass.enumerate op should define all lazy properties not -// yet reflected in obj. +/** + * The old-style JSClass.enumerate op should define all lazy properties not + * yet reflected in obj. + */ typedef bool (* JSEnumerateOp)(JSContext* cx, JS::HandleObject obj); -// Resolve a lazy property named by id in obj by defining it directly in obj. -// Lazy properties are those reflected from some peer native property space -// (e.g., the DOM attributes for a given node reflected as obj) on demand. -// -// JS looks for a property in an object, and if not found, tries to resolve -// the given id. *resolvedp should be set to true iff the property was -// was defined on |obj|. -// +/** + * Resolve a lazy property named by id in obj by defining it directly in obj. + * Lazy properties are those reflected from some peer native property space + * (e.g., the DOM attributes for a given node reflected as obj) on demand. + * + * JS looks for a property in an object, and if not found, tries to resolve + * the given id. *resolvedp should be set to true iff the property was + * was defined on |obj|. + */ typedef bool (* JSResolveOp)(JSContext* cx, JS::HandleObject obj, JS::HandleId id, bool* resolvedp); -// A class with a resolve hook can optionally have a mayResolve hook. This hook -// must have no side effects and must return true for a given id if the resolve -// hook may resolve this id. This is useful when we're doing a "pure" lookup: if -// mayResolve returns false, we know we don't have to call the effectful resolve -// hook. -// -// maybeObj, if non-null, is the object on which we're doing the lookup. This -// can be nullptr: during JIT compilation we sometimes know the Class but not -// the object. +/** + * A class with a resolve hook can optionally have a mayResolve hook. This hook + * must have no side effects and must return true for a given id if the resolve + * hook may resolve this id. This is useful when we're doing a "pure" lookup: if + * mayResolve returns false, we know we don't have to call the effectful resolve + * hook. + * + * maybeObj, if non-null, is the object on which we're doing the lookup. This + * can be nullptr: during JIT compilation we sometimes know the Class but not + * the object. + */ typedef bool (* JSMayResolveOp)(const JSAtomState& names, jsid id, JSObject* maybeObj); -// Finalize obj, which the garbage collector has determined to be unreachable -// from other live objects or from GC roots. Obviously, finalizers must never -// store a reference to obj. +/** + * Finalize obj, which the garbage collector has determined to be unreachable + * from other live objects or from GC roots. Obviously, finalizers must never + * store a reference to obj. + */ typedef void (* JSFinalizeOp)(JSFreeOp* fop, JSObject* obj); -// Finalizes external strings created by JS_NewExternalString. +/** Finalizes external strings created by JS_NewExternalString. */ struct JSStringFinalizer { void (*finalize)(const JSStringFinalizer* fin, char16_t* chars); }; -// Check whether v is an instance of obj. Return false on error or exception, -// true on success with true in *bp if v is an instance of obj, false in -// *bp otherwise. +/** + * Check whether v is an instance of obj. Return false on error or exception, + * true on success with true in *bp if v is an instance of obj, false in + * *bp otherwise. + */ typedef bool (* JSHasInstanceOp)(JSContext* cx, JS::HandleObject obj, JS::MutableHandleValue vp, bool* bp); -// Function type for trace operation of the class called to enumerate all -// traceable things reachable from obj's private data structure. For each such -// thing, a trace implementation must call one of the JS_Call*Tracer variants -// on the thing. -// -// JSTraceOp implementation can assume that no other threads mutates object -// state. It must not change state of the object or corresponding native -// structures. The only exception for this rule is the case when the embedding -// needs a tight integration with GC. In that case the embedding can check if -// the traversal is a part of the marking phase through calling -// JS_IsGCMarkingTracer and apply a special code like emptying caches or -// marking its native structures. +/** + * Function type for trace operation of the class called to enumerate all + * traceable things reachable from obj's private data structure. For each such + * thing, a trace implementation must call one of the JS_Call*Tracer variants + * on the thing. + * + * JSTraceOp implementation can assume that no other threads mutates object + * state. It must not change state of the object or corresponding native + * structures. The only exception for this rule is the case when the embedding + * needs a tight integration with GC. In that case the embedding can check if + * the traversal is a part of the marking phase through calling + * JS_IsGCMarkingTracer and apply a special code like emptying caches or + * marking its native structures. + */ typedef void (* JSTraceOp)(JSTracer* trc, JSObject* obj); @@ -440,12 +465,14 @@ typedef bool (* GetElementsOp)(JSContext* cx, JS::HandleObject obj, uint32_t begin, uint32_t end, ElementAdder* adder); -// A generic type for functions mapping an object to another object, or null -// if an error or exception was thrown on cx. +/** + * A generic type for functions mapping an object to another object, or null + * if an error or exception was thrown on cx. + */ typedef JSObject* (* ObjectOp)(JSContext* cx, JS::HandleObject obj); -// Hook to map an object to its inner object. Infallible. +/** Hook to map an object to its inner object. Infallible. */ typedef JSObject* (* InnerObjectOp)(JSObject* obj); @@ -470,10 +497,10 @@ typedef void JSNative construct; \ JSTraceOp trace -// Callback for the creation of constructor and prototype objects. +/** Callback for the creation of constructor and prototype objects. */ typedef JSObject* (*ClassObjectCreationOp)(JSContext* cx, JSProtoKey key); -// Callback for custom post-processing after class initialization via ClassSpec. +/** Callback for custom post-processing after class initialization via ClassSpec. */ typedef bool (*FinishClassInitOp)(JSContext* cx, JS::HandleObject ctor, JS::HandleObject proto); @@ -565,13 +592,13 @@ struct ClassExtension ObjectOp outerObject; InnerObjectOp innerObject; - /* + /** * isWrappedNative is true only if the class is an XPCWrappedNative. * WeakMaps use this to override the wrapper disposal optimization. */ bool isWrappedNative; - /* + /** * If an object is used as a key in a weakmap, it may be desirable for the * garbage collector to keep that object around longer than it otherwise * would. A common case is when the key is a wrapper around an object in @@ -584,7 +611,7 @@ struct ClassExtension */ JSWeakmapKeyDelegateOp weakmapKeyDelegateOp; - /* + /** * Optional hook called when an object is moved by a compacting GC. * * There may exist weak pointers to an object that are not traced through @@ -816,7 +843,7 @@ Valueify(const JSClass* c) return (const Class*)c; } -/* +/** * Enumeration describing possible values of the [[Class]] internal property * value of objects. */ @@ -825,7 +852,7 @@ enum ESClassValue { ESClass_Boolean, ESClass_RegExp, ESClass_ArrayBuffer, ESClass_SharedArrayBuffer, ESClass_Date, ESClass_Set, ESClass_Map, - // None of the above. + /** None of the above. */ ESClass_Other }; diff --git a/js/public/Conversions.h b/js/public/Conversions.h index 6c4e1187d0b9..c08da01346d3 100644 --- a/js/public/Conversions.h +++ b/js/public/Conversions.h @@ -75,7 +75,7 @@ namespace JS { namespace detail { #ifdef JS_DEBUG -/* +/** * Assert that we're not doing GC on cx, that we're in a request as * needed, and that the compartments for cx and v are correct. * Also check that GC would be safe at this point. @@ -89,7 +89,7 @@ inline void AssertArgumentsAreSane(JSContext* cx, HandleValue v) } // namespace detail -/* +/** * ES6 draft 20141224, 7.1.1, second algorithm. * * Most users shouldn't call this -- use JS::ToBoolean, ToNumber, or ToString diff --git a/js/public/GCAPI.h b/js/public/GCAPI.h index d4240f3b2f4d..90f8e4eba3f7 100644 --- a/js/public/GCAPI.h +++ b/js/public/GCAPI.h @@ -22,20 +22,20 @@ struct Statistics; } // namespace js typedef enum JSGCMode { - /* Perform only global GCs. */ + /** Perform only global GCs. */ JSGC_MODE_GLOBAL = 0, - /* Perform per-compartment GCs until too much garbage has accumulated. */ + /** Perform per-compartment GCs until too much garbage has accumulated. */ JSGC_MODE_COMPARTMENT = 1, - /* + /** * Collect in short time slices rather than all at once. Implies * JSGC_MODE_COMPARTMENT. */ JSGC_MODE_INCREMENTAL = 2 } JSGCMode; -/* +/** * Kinds of js_GC invocation. */ typedef enum JSGCInvocationKind { @@ -146,19 +146,19 @@ enum Reason { * all zones. Failing to select any zone is an error. */ -/* +/** * Schedule the given zone to be collected as part of the next GC. */ extern JS_PUBLIC_API(void) PrepareZoneForGC(Zone* zone); -/* +/** * Schedule all zones to be collected in the next GC. */ extern JS_PUBLIC_API(void) PrepareForFullGC(JSRuntime* rt); -/* +/** * When performing an incremental GC, the zones that were selected for the * previous incremental slice must be selected in subsequent slices as well. * This function selects those slices automatically. @@ -166,14 +166,14 @@ PrepareForFullGC(JSRuntime* rt); extern JS_PUBLIC_API(void) PrepareForIncrementalGC(JSRuntime* rt); -/* +/** * Returns true if any zone in the system has been scheduled for GC with one of * the functions above or by the JS engine. */ extern JS_PUBLIC_API(bool) IsGCScheduled(JSRuntime* rt); -/* +/** * Undoes the effect of the Prepare methods above. The given zone will not be * collected in the next GC. */ @@ -186,7 +186,7 @@ SkipZoneForGC(Zone* zone); * The following functions perform a non-incremental GC. */ -/* +/** * Performs a non-incremental collection of all selected zones. * * If the gckind argument is GC_NORMAL, then some objects that are unreachable @@ -218,7 +218,7 @@ GCForReason(JSRuntime* rt, JSGCInvocationKind gckind, gcreason::Reason reason); * non-incremental collections can still happen when low on memory. */ -/* +/** * Begin an incremental collection and perform one slice worth of work. When * this function returns, the collection may not be complete. * IncrementalGCSlice() must be called repeatedly until @@ -231,7 +231,7 @@ extern JS_PUBLIC_API(void) StartIncrementalGC(JSRuntime* rt, JSGCInvocationKind gckind, gcreason::Reason reason, int64_t millis = 0); -/* +/** * Perform a slice of an ongoing incremental collection. When this function * returns, the collection may not be complete. It must be called repeatedly * until !IsIncrementalGCInProgress(rt). @@ -242,7 +242,7 @@ StartIncrementalGC(JSRuntime* rt, JSGCInvocationKind gckind, gcreason::Reason re extern JS_PUBLIC_API(void) IncrementalGCSlice(JSRuntime* rt, gcreason::Reason reason, int64_t millis = 0); -/* +/** * If IsIncrementalGCInProgress(rt), this call finishes the ongoing collection * by performing an arbitrarily long slice. If !IsIncrementalGCInProgress(rt), * this is equivalent to GCForReason. When this function returns, @@ -251,7 +251,7 @@ IncrementalGCSlice(JSRuntime* rt, gcreason::Reason reason, int64_t millis = 0); extern JS_PUBLIC_API(void) FinishIncrementalGC(JSRuntime* rt, gcreason::Reason reason); -/* +/** * If IsIncrementalGCInProgress(rt), this call aborts the ongoing collection and * performs whatever work needs to be done to return the collector to its idle * state. This may take an arbitrarily long time. When this function returns, @@ -345,7 +345,7 @@ struct JS_PUBLIC_API(GCDescription) { typedef void (* GCSliceCallback)(JSRuntime* rt, GCProgress progress, const GCDescription& desc); -/* +/** * The GC slice callback is called at the beginning and end of each slice. This * callback may be used for GC notifications as well as to perform additional * marking. @@ -353,7 +353,7 @@ typedef void extern JS_PUBLIC_API(GCSliceCallback) SetGCSliceCallback(JSRuntime* rt, GCSliceCallback callback); -/* +/** * Incremental GC defaults to enabled, but may be disabled for testing or in * embeddings that have not yet implemented barriers on their native classes. * There is not currently a way to re-enable incremental GC once it has been @@ -362,7 +362,7 @@ SetGCSliceCallback(JSRuntime* rt, GCSliceCallback callback); extern JS_PUBLIC_API(void) DisableIncrementalGC(JSRuntime* rt); -/* +/** * Returns true if incremental GC is enabled. Simply having incremental GC * enabled is not sufficient to ensure incremental collections are happening. * See the comment "Incremental GC" above for reasons why incremental GC may be @@ -373,7 +373,7 @@ DisableIncrementalGC(JSRuntime* rt); extern JS_PUBLIC_API(bool) IsIncrementalGCEnabled(JSRuntime* rt); -/* +/** * Returns true while an incremental GC is ongoing, both when actively * collecting and between slices. */ @@ -404,7 +404,7 @@ IncrementalValueBarrier(const Value& v); extern JS_PUBLIC_API(void) IncrementalObjectBarrier(JSObject* obj); -/* +/** * Returns true if the most recent GC ran incrementally. */ extern JS_PUBLIC_API(bool) @@ -418,7 +418,7 @@ WasIncrementalGC(JSRuntime* rt); * --enable-gcgenerational. */ -/* Ensure that generational GC is disabled within some scope. */ +/** Ensure that generational GC is disabled within some scope. */ class JS_PUBLIC_API(AutoDisableGenerationalGC) { js::gc::GCRuntime* gc; @@ -428,14 +428,14 @@ class JS_PUBLIC_API(AutoDisableGenerationalGC) ~AutoDisableGenerationalGC(); }; -/* +/** * Returns true if generational allocation and collection is currently enabled * on the given runtime. */ extern JS_PUBLIC_API(bool) IsGenerationalGCEnabled(JSRuntime* rt); -/* +/** * Returns the GC's "number". This does not correspond directly to the number * of GCs that have been run, but is guaranteed to be monotonically increasing * with GC activity. @@ -443,7 +443,7 @@ IsGenerationalGCEnabled(JSRuntime* rt); extern JS_PUBLIC_API(size_t) GetGCNumber(); -/* +/** * The GC does not immediately return the unused memory freed by a collection * back to the system incase it is needed soon afterwards. This call forces the * GC to return this memory immediately. @@ -451,7 +451,7 @@ GetGCNumber(); extern JS_PUBLIC_API(void) ShrinkGCBuffers(JSRuntime* rt); -/* +/** * Assert if a GC occurs while this class is live. This class does not disable * the static rooting hazard analysis. */ @@ -477,7 +477,7 @@ class JS_PUBLIC_API(AutoAssertOnGC) #endif }; -/* +/** * Assert if an allocation of a GC thing occurs while this class is live. This * class does not disable the static rooting hazard analysis. */ @@ -499,7 +499,7 @@ class JS_PUBLIC_API(AutoAssertNoAlloc) #endif }; -/* +/** * Disable the static rooting hazard analysis in the live region and assert if * any allocation that could potentially trigger a GC occurs while this guard * object is live. This is most useful to help the exact rooting hazard analysis @@ -520,7 +520,7 @@ class JS_PUBLIC_API(AutoSuppressGCAnalysis) : public AutoAssertNoAlloc explicit AutoSuppressGCAnalysis(JSRuntime* rt) : AutoAssertNoAlloc(rt) {} }; -/* +/** * Assert that code is only ever called from a GC callback, disable the static * rooting hazard analysis and assert if any allocation that could potentially * trigger a GC occurs while this guard object is live. @@ -534,7 +534,7 @@ class JS_PUBLIC_API(AutoAssertGCCallback) : public AutoSuppressGCAnalysis explicit AutoAssertGCCallback(JSObject* obj); }; -/* +/** * Place AutoCheckCannotGC in scopes that you believe can never GC. These * annotations will be verified both dynamically via AutoAssertOnGC, and * statically with the rooting hazard analysis (implemented by making the @@ -551,7 +551,7 @@ class JS_PUBLIC_API(AutoCheckCannotGC) : public AutoAssertOnGC explicit AutoCheckCannotGC(JSRuntime* rt) : AutoAssertOnGC(rt) {} }; -/* +/** * Unsets the gray bit for anything reachable from |thing|. |kind| should not be * JS::TraceKind::Shape. |thing| should be non-null. */ diff --git a/js/public/HeapAPI.h b/js/public/HeapAPI.h index 016d9f1953b3..ba9fcbcf0ce1 100644 --- a/js/public/HeapAPI.h +++ b/js/public/HeapAPI.h @@ -149,11 +149,13 @@ struct Zone } /* namespace shadow */ -// A GC pointer, tagged with the trace kind. -// -// In general, a GC pointer should be stored with an exact type. This class -// is for use when that is not possible because a single pointer must point -// to several kinds of GC thing. +/** + * A GC pointer, tagged with the trace kind. + * + * In general, a GC pointer should be stored with an exact type. This class + * is for use when that is not possible because a single pointer must point + * to several kinds of GC thing. + */ class JS_FRIEND_API(GCCellPtr) { public: @@ -405,7 +407,7 @@ IsIncrementalBarrierNeededOnTenuredGCThing(JS::shadow::Runtime* rt, const JS::GC return JS::shadow::Zone::asShadowZone(zone)->needsIncrementalBarrier(); } -/* +/** * Create an object providing access to the garbage collector's internal notion * of the current state of memory (both GC heap memory and GCthing-controlled * malloc memory. diff --git a/js/public/Id.h b/js/public/Id.h index 51c851835019..a62b2c8dd0b4 100644 --- a/js/public/Id.h +++ b/js/public/Id.h @@ -58,7 +58,7 @@ JSID_TO_STRING(jsid id) return (JSString*)JSID_BITS(id); } -/* +/** * Only JSStrings that have been interned via the JSAPI can be turned into * jsids by API clients. * diff --git a/js/public/MemoryMetrics.h b/js/public/MemoryMetrics.h index 7fae00000a0a..7427f4aa56cd 100644 --- a/js/public/MemoryMetrics.h +++ b/js/public/MemoryMetrics.h @@ -55,8 +55,7 @@ struct TabSizes size_t other; }; -// These are the measurements used by Servo. It's important that this is a POD -// struct so that Servo can have a parallel |repr(C)| Rust equivalent. +/** These are the measurements used by Servo. */ struct ServoSizes { enum Kind { @@ -96,18 +95,22 @@ struct ServoSizes namespace js { -// In memory reporting, we have concept of "sundries", line items which are too -// small to be worth reporting individually. Under some circumstances, a memory -// reporter gets tossed into the sundries bucket if it's smaller than -// MemoryReportingSundriesThreshold() bytes. -// -// We need to define this value here, rather than in the code which actually -// generates the memory reports, because NotableStringInfo uses this value. +/** + * In memory reporting, we have concept of "sundries", line items which are too + * small to be worth reporting individually. Under some circumstances, a memory + * reporter gets tossed into the sundries bucket if it's smaller than + * MemoryReportingSundriesThreshold() bytes. + * + * We need to define this value here, rather than in the code which actually + * generates the memory reports, because NotableStringInfo uses this value. + */ JS_FRIEND_API(size_t) MemoryReportingSundriesThreshold(); -// This hash policy avoids flattening ropes (which perturbs the site being -// measured and requires a JSContext) at the expense of doing a FULL ROPE COPY -// on every hash and match! Beware. +/** + * This hash policy avoids flattening ropes (which perturbs the site being + * measured and requires a JSContext) at the expense of doing a FULL ROPE COPY + * on every hash and match! Beware. + */ struct InefficientNonFlatteningStringHashPolicy { typedef JSString* Lookup; @@ -221,12 +224,14 @@ struct ClassInfo #undef FOR_EACH_SIZE }; -// Holds data about a notable class (one whose combined object and shape -// instances use more than a certain amount of memory) so we can report it -// individually. -// -// The only difference between this class and ClassInfo is that this class -// holds a copy of the filename. +/** + * Holds data about a notable class (one whose combined object and shape + * instances use more than a certain amount of memory) so we can report it + * individually. + * + * The only difference between this class and ClassInfo is that this class + * holds a copy of the filename. + */ struct NotableClassInfo : public ClassInfo { NotableClassInfo(); @@ -244,7 +249,7 @@ struct NotableClassInfo : public ClassInfo NotableClassInfo(const NotableClassInfo& info) = delete; }; -// Data for tracking JIT-code memory usage. +/** Data for tracking JIT-code memory usage. */ struct CodeSizes { #define FOR_EACH_SIZE(macro) \ @@ -269,7 +274,7 @@ struct CodeSizes #undef FOR_EACH_SIZE }; -// Data for tracking GC memory usage. +/** Data for tracking GC memory usage. */ struct GCSizes { // |nurseryDecommitted| is marked as NonHeap rather than GCHeapDecommitted @@ -300,11 +305,13 @@ struct GCSizes #undef FOR_EACH_SIZE }; -// This class holds information about the memory taken up by identical copies of -// a particular string. Multiple JSStrings may have their sizes aggregated -// together into one StringInfo object. Note that two strings with identical -// chars will not be aggregated together if one is a short string and the other -// is not. +/** + * This class holds information about the memory taken up by identical copies of + * a particular string. Multiple JSStrings may have their sizes aggregated + * together into one StringInfo object. Note that two strings with identical + * chars will not be aggregated together if one is a short string and the other + * is not. + */ struct StringInfo { #define FOR_EACH_SIZE(macro) \ @@ -355,11 +362,13 @@ struct StringInfo #undef FOR_EACH_SIZE }; -// Holds data about a notable string (one which, counting all duplicates, uses -// more than a certain amount of memory) so we can report it individually. -// -// The only difference between this class and StringInfo is that -// NotableStringInfo holds a copy of some or all of the string's chars. +/** + * Holds data about a notable string (one which, counting all duplicates, uses + * more than a certain amount of memory) so we can report it individually. + * + * The only difference between this class and StringInfo is that + * NotableStringInfo holds a copy of some or all of the string's chars. + */ struct NotableStringInfo : public StringInfo { static const size_t MAX_SAVED_CHARS = 1024; @@ -380,8 +389,10 @@ struct NotableStringInfo : public StringInfo NotableStringInfo(const NotableStringInfo& info) = delete; }; -// This class holds information about the memory taken up by script sources -// from a particular file. +/** + * This class holds information about the memory taken up by script sources + * from a particular file. + */ struct ScriptSourceInfo { #define FOR_EACH_SIZE(macro) \ @@ -422,12 +433,14 @@ struct ScriptSourceInfo #undef FOR_EACH_SIZE }; -// Holds data about a notable script source file (one whose combined -// script sources use more than a certain amount of memory) so we can report it -// individually. -// -// The only difference between this class and ScriptSourceInfo is that this -// class holds a copy of the filename. +/** + * Holds data about a notable script source file (one whose combined + * script sources use more than a certain amount of memory) so we can report it + * individually. + * + * The only difference between this class and ScriptSourceInfo is that this + * class holds a copy of the filename. + */ struct NotableScriptSourceInfo : public ScriptSourceInfo { NotableScriptSourceInfo(); @@ -445,8 +458,10 @@ struct NotableScriptSourceInfo : public ScriptSourceInfo NotableScriptSourceInfo(const NotableScriptSourceInfo& info) = delete; }; -// These measurements relate directly to the JSRuntime, and not to zones and -// compartments within it. +/** + * These measurements relate directly to the JSRuntime, and not to zones and + * compartments within it. + */ struct RuntimeSizes { #define FOR_EACH_SIZE(macro) \ diff --git a/js/public/RootingAPI.h b/js/public/RootingAPI.h index 6b565bfb4260..d444b859db77 100644 --- a/js/public/RootingAPI.h +++ b/js/public/RootingAPI.h @@ -180,7 +180,7 @@ JS_FRIEND_API(bool) isGCEnabled(); JS_FRIEND_API(void) HeapObjectPostBarrier(JSObject** objp, JSObject* prev, JSObject* next); #ifdef JS_DEBUG -/* +/** * For generational GC, assert that an object is in the tenured generation as * opposed to being in the nursery. */ @@ -195,7 +195,7 @@ inline void AssertGCThingIsNotAnObjectSubclass(js::gc::Cell* cell) {} #endif -/* +/** * The Heap class is a heap-stored reference to a JS GC thing. All members of * heap classes that refer to GC things should use Heap (or possibly * TenuredHeap, described below). @@ -278,7 +278,7 @@ class Heap : public js::HeapBase T ptr; }; -/* +/** * The TenuredHeap class is similar to the Heap class above in that it * encapsulates the GC concerns of an on-heap reference to a JS object. However, * it has two important differences: @@ -368,7 +368,7 @@ class TenuredHeap : public js::HeapBase uintptr_t bits; }; -/* +/** * Reference to a T that has been rooted elsewhere. This is most useful * as a parameter type, which guarantees that the T lvalue is properly * rooted. See "Move GC Stack Rooting" above. @@ -457,7 +457,7 @@ class MOZ_NONHEAP_CLASS Handle : public js::HandleBase const T* ptr; }; -/* +/** * Similar to a handle, but the underlying storage can be changed. This is * useful for outparams. * @@ -509,7 +509,7 @@ class MOZ_STACK_CLASS MutableHandle : public js::MutableHandleBase namespace js { -/* +/** * By default, things should use the inheritance hierarchy to find their * ThingRootKind. Some pointer types are explicitly set in jspubtd.h so that * Rooted may be used without the class definition being available. @@ -645,7 +645,7 @@ RootListsForRootingContext(js::PerThreadDataFriendFields* pt) namespace JS { -/* +/** * Local variable of type T whose value is always rooted. This is typically * used for local variables, or for non-rooted values being passed to a * function that requires a handle, e.g. Foo(Root(cx, x)). @@ -733,7 +733,7 @@ class MOZ_RAII Rooted : public js::RootedBase namespace js { -/* +/** * Augment the generic Rooted interface when T = JSObject* with * class-querying and downcasting operations. * @@ -751,7 +751,7 @@ class RootedBase JS::Handle as() const; }; -/* +/** * Augment the generic Handle interface when T = JSObject* with * downcasting operations. * @@ -769,7 +769,7 @@ class HandleBase JS::Handle as() const; }; -/* Interface substitute for Rooted which does not root the variable's memory. */ +/** Interface substitute for Rooted which does not root the variable's memory. */ template class MOZ_RAII FakeRooted : public RootedBase { @@ -796,7 +796,7 @@ class MOZ_RAII FakeRooted : public RootedBase FakeRooted(const FakeRooted&) = delete; }; -/* Interface substitute for MutableHandle which is not required to point to rooted memory. */ +/** Interface substitute for MutableHandle which is not required to point to rooted memory. */ template class FakeMutableHandle : public js::MutableHandleBase { @@ -824,7 +824,7 @@ class FakeMutableHandle : public js::MutableHandleBase T* ptr; }; -/* +/** * Types for a variable that either should or shouldn't be rooted, depending on * the template parameter allowGC. Used for implementing functions that can * operate on either rooted or unrooted data. @@ -930,7 +930,7 @@ MutableHandle::MutableHandle(PersistentRooted* root) ptr = root->address(); } -/* +/** * A copyable, assignable global GC root type with arbitrary lifetime, an * infallible constructor, and automatic unrooting on destruction. * diff --git a/js/public/StructuredClone.h b/js/public/StructuredClone.h index 2930a6073a1f..e3077c72a595 100644 --- a/js/public/StructuredClone.h +++ b/js/public/StructuredClone.h @@ -23,85 +23,96 @@ struct JSStructuredCloneWriter; namespace JS { enum TransferableOwnership { - // Transferable data has not been filled in yet + /** Transferable data has not been filled in yet */ SCTAG_TMO_UNFILLED = 0, - // Structured clone buffer does not yet own the data + /** Structured clone buffer does not yet own the data */ SCTAG_TMO_UNOWNED = 1, - // All values at least this large are owned by the clone buffer + /** All values at least this large are owned by the clone buffer */ SCTAG_TMO_FIRST_OWNED = 2, - // Data is a pointer that can be freed + /** Data is a pointer that can be freed */ SCTAG_TMO_ALLOC_DATA = 2, - // Data is a SharedArrayBufferObject's buffer + /** Data is a SharedArrayBufferObject's buffer */ SCTAG_TMO_SHARED_BUFFER = 3, - // Data is a memory mapped pointer + /** Data is a memory mapped pointer */ SCTAG_TMO_MAPPED_DATA = 4, - // Data is embedding-specific. The engine can free it by calling the - // freeTransfer op. The embedding can also use SCTAG_TMO_USER_MIN and - // greater, up to 32 bits, to distinguish specific ownership variants. + /** + * Data is embedding-specific. The engine can free it by calling the + * freeTransfer op. The embedding can also use SCTAG_TMO_USER_MIN and + * greater, up to 32 bits, to distinguish specific ownership variants. + */ SCTAG_TMO_CUSTOM = 5, SCTAG_TMO_USER_MIN }; } /* namespace JS */ -// Read structured data from the reader r. This hook is used to read a value -// previously serialized by a call to the WriteStructuredCloneOp hook. -// -// tag and data are the pair of uint32_t values from the header. The callback -// may use the JS_Read* APIs to read any other relevant parts of the object -// from the reader r. closure is any value passed to the JS_ReadStructuredClone -// function. Return the new object on success, nullptr on error/exception. +/** + * Read structured data from the reader r. This hook is used to read a value + * previously serialized by a call to the WriteStructuredCloneOp hook. + * + * tag and data are the pair of uint32_t values from the header. The callback + * may use the JS_Read* APIs to read any other relevant parts of the object + * from the reader r. closure is any value passed to the JS_ReadStructuredClone + * function. Return the new object on success, nullptr on error/exception. + */ typedef JSObject* (*ReadStructuredCloneOp)(JSContext* cx, JSStructuredCloneReader* r, uint32_t tag, uint32_t data, void* closure); -// Structured data serialization hook. The engine can write primitive values, -// Objects, Arrays, Dates, RegExps, TypedArrays, ArrayBuffers, Sets, Maps, -// and SharedTypedArrays. Any other type of object requires application support. -// This callback must first use the JS_WriteUint32Pair API to write an object -// header, passing a value greater than JS_SCTAG_USER to the tag parameter. -// Then it can use the JS_Write* APIs to write any other relevant parts of -// the value v to the writer w. closure is any value passed to the -// JS_WriteStructuredClone function. -// -// Return true on success, false on error/exception. +/** + * Structured data serialization hook. The engine can write primitive values, + * Objects, Arrays, Dates, RegExps, TypedArrays, ArrayBuffers, Sets, Maps, + * and SharedTypedArrays. Any other type of object requires application support. + * This callback must first use the JS_WriteUint32Pair API to write an object + * header, passing a value greater than JS_SCTAG_USER to the tag parameter. + * Then it can use the JS_Write* APIs to write any other relevant parts of + * the value v to the writer w. closure is any value passed to the + * JS_WriteStructuredClone function. + * + * Return true on success, false on error/exception. + */ typedef bool (*WriteStructuredCloneOp)(JSContext* cx, JSStructuredCloneWriter* w, JS::HandleObject obj, void* closure); -// This is called when JS_WriteStructuredClone is given an invalid transferable. -// To follow HTML5, the application must throw a DATA_CLONE_ERR DOMException -// with error set to one of the JS_SCERR_* values. +/** + * This is called when JS_WriteStructuredClone is given an invalid transferable. + * To follow HTML5, the application must throw a DATA_CLONE_ERR DOMException + * with error set to one of the JS_SCERR_* values. + */ typedef void (*StructuredCloneErrorOp)(JSContext* cx, uint32_t errorid); -// This is called when JS_ReadStructuredClone receives a transferable object -// not known to the engine. If this hook does not exist or returns false, the -// JS engine calls the reportError op if set, otherwise it throws a -// DATA_CLONE_ERR DOM Exception. This method is called before any other -// callback and must return a non-null object in returnObject on success. +/** + * This is called when JS_ReadStructuredClone receives a transferable object + * not known to the engine. If this hook does not exist or returns false, the + * JS engine calls the reportError op if set, otherwise it throws a + * DATA_CLONE_ERR DOM Exception. This method is called before any other + * callback and must return a non-null object in returnObject on success. + */ typedef bool (*ReadTransferStructuredCloneOp)(JSContext* cx, JSStructuredCloneReader* r, uint32_t tag, void* content, uint64_t extraData, void* closure, JS::MutableHandleObject returnObject); -// Called when JS_WriteStructuredClone receives a transferable object not -// handled by the engine. If this hook does not exist or returns false, the JS -// engine will call the reportError hook or fall back to throwing a -// DATA_CLONE_ERR DOM Exception. This method is called before any other -// callback. -// -// tag: indicates what type of transferable this is. Must be greater than -// 0xFFFF0201 (value of the internal SCTAG_TRANSFER_MAP_PENDING_ENTRY) -// -// ownership: see TransferableOwnership, above. Used to communicate any needed -// ownership info to the FreeTransferStructuredCloneOp. -// -// content, extraData: what the ReadTransferStructuredCloneOp will receive -// +/** + * Called when JS_WriteStructuredClone receives a transferable object not + * handled by the engine. If this hook does not exist or returns false, the JS + * engine will call the reportError hook or fall back to throwing a + * DATA_CLONE_ERR DOM Exception. This method is called before any other + * callback. + * + * tag: indicates what type of transferable this is. Must be greater than + * 0xFFFF0201 (value of the internal SCTAG_TRANSFER_MAP_PENDING_ENTRY) + * + * ownership: see TransferableOwnership, above. Used to communicate any needed + * ownership info to the FreeTransferStructuredCloneOp. + * + * content, extraData: what the ReadTransferStructuredCloneOp will receive + */ typedef bool (*TransferStructuredCloneOp)(JSContext* cx, JS::Handle obj, void* closure, @@ -111,9 +122,11 @@ typedef bool (*TransferStructuredCloneOp)(JSContext* cx, void** content, uint64_t* extraData); -// Called when JS_ClearStructuredClone has to free an unknown transferable -// object. Note that it should never trigger a garbage collection (and will -// assert in a debug build if it does.) +/** + * Called when JS_ClearStructuredClone has to free an unknown transferable + * object. Note that it should never trigger a garbage collection (and will + * assert in a debug build if it does.) + */ typedef void (*FreeTransferStructuredCloneOp)(uint32_t tag, JS::TransferableOwnership ownership, void* content, uint64_t extraData, void* closure); @@ -132,14 +145,16 @@ struct JSStructuredCloneCallbacks { FreeTransferStructuredCloneOp freeTransfer; }; -// Note: if the *data contains transferable objects, it can be read only once. +/** Note: if the *data contains transferable objects, it can be read only once. */ JS_PUBLIC_API(bool) JS_ReadStructuredClone(JSContext* cx, uint64_t* data, size_t nbytes, uint32_t version, JS::MutableHandleValue vp, const JSStructuredCloneCallbacks* optionalCallbacks, void* closure); -// Note: On success, the caller is responsible for calling -// JS_ClearStructuredClone(*datap, nbytes, optionalCallbacks, closure). +/** + * Note: On success, the caller is responsible for calling + * JS_ClearStructuredClone(*datap, nbytes, optionalCallbacks, closure). + */ JS_PUBLIC_API(bool) JS_WriteStructuredClone(JSContext* cx, JS::HandleValue v, uint64_t** datap, size_t* nbytesp, const JSStructuredCloneCallbacks* optionalCallbacks, @@ -157,7 +172,7 @@ JS_PUBLIC_API(bool) JS_StructuredClone(JSContext* cx, JS::HandleValue v, JS::MutableHandleValue vp, const JSStructuredCloneCallbacks* optionalCallbacks, void* closure); -// RAII sugar for JS_WriteStructuredClone. +/** RAII sugar for JS_WriteStructuredClone. */ class JS_PUBLIC_API(JSAutoStructuredCloneBuffer) { uint64_t* data_; size_t nbytes_; @@ -194,26 +209,32 @@ class JS_PUBLIC_API(JSAutoStructuredCloneBuffer) { void clear(const JSStructuredCloneCallbacks* optionalCallbacks=nullptr, void* closure=nullptr); - // Copy some memory. It will be automatically freed by the destructor. + /** Copy some memory. It will be automatically freed by the destructor. */ bool copy(const uint64_t* data, size_t nbytes, uint32_t version=JS_STRUCTURED_CLONE_VERSION, const JSStructuredCloneCallbacks* callbacks=nullptr, void* closure=nullptr); - // Adopt some memory. It will be automatically freed by the destructor. - // data must have been allocated by the JS engine (e.g., extracted via - // JSAutoStructuredCloneBuffer::steal). + /** + * Adopt some memory. It will be automatically freed by the destructor. + * data must have been allocated by the JS engine (e.g., extracted via + * JSAutoStructuredCloneBuffer::steal). + */ void adopt(uint64_t* data, size_t nbytes, uint32_t version=JS_STRUCTURED_CLONE_VERSION, const JSStructuredCloneCallbacks* callbacks=nullptr, void* closure=nullptr); - // Release the buffer and transfer ownership to the caller. The caller is - // responsible for calling JS_ClearStructuredClone or feeding the memory - // back to JSAutoStructuredCloneBuffer::adopt. + /** + * Release the buffer and transfer ownership to the caller. The caller is + * responsible for calling JS_ClearStructuredClone or feeding the memory + * back to JSAutoStructuredCloneBuffer::adopt. + */ void steal(uint64_t** datap, size_t* nbytesp, uint32_t* versionp=nullptr, const JSStructuredCloneCallbacks** callbacks=nullptr, void** closure=nullptr); - // Abandon ownership of any transferable objects stored in the buffer, - // without freeing the buffer itself. Useful when copying the data out into - // an external container, though note that you will need to use adopt() or - // JS_ClearStructuredClone to properly release that data eventually. + /** + * Abandon ownership of any transferable objects stored in the buffer, + * without freeing the buffer itself. Useful when copying the data out into + * an external container, though note that you will need to use adopt() or + * JS_ClearStructuredClone to properly release that data eventually. + */ void abandon() { ownTransferables_ = IgnoreTransferablesIfAny; } bool read(JSContext* cx, JS::MutableHandleValue vp, diff --git a/js/public/TracingAPI.h b/js/public/TracingAPI.h index f5f0fed2ee01..1484f5307279 100644 --- a/js/public/TracingAPI.h +++ b/js/public/TracingAPI.h @@ -20,27 +20,33 @@ class JS_PUBLIC_API(CallbackTracer); template class Heap; template class TenuredHeap; -// Returns a static string equivalent of |kind|. +/** Returns a static string equivalent of |kind|. */ JS_FRIEND_API(const char*) GCTraceKindToAscii(JS::TraceKind kind); } // namespace JS enum WeakMapTraceKind { - // Do true ephemeron marking with an iterative weak marking phase. + /** Do true ephemeron marking with an iterative weak marking phase. */ DoNotTraceWeakMaps, - // Do true ephemeron marking with a weak key lookup marking phase. This is - // expected to be constant for the lifetime of a JSTracer; it does not - // change when switching from "plain" marking to weak marking. + /** + * Do true ephemeron marking with a weak key lookup marking phase. This is + * expected to be constant for the lifetime of a JSTracer; it does not + * change when switching from "plain" marking to weak marking. + */ ExpandWeakMaps, - // Trace through to all values, irrespective of whether the keys are live - // or not. Used for non-marking tracers. + /** + * Trace through to all values, irrespective of whether the keys are live + * or not. Used for non-marking tracers. + */ TraceWeakMapValues, - // Trace through to all keys and values, irrespective of whether the keys - // are live or not. Used for non-marking tracers. + /** + * Trace through to all keys and values, irrespective of whether the keys + * are live or not. Used for non-marking tracers. + */ TraceWeakMapKeysValues }; @@ -333,8 +339,10 @@ JS_CallHashSetObjectTracer(JSTracer* trc, HashSetEnum& e, JSObject* const& key, e.rekeyFront(updated); } -// Trace an object that is known to always be tenured. No post barriers are -// required in this case. +/** + * Trace an object that is known to always be tenured. No post barriers are + * required in this case. + */ extern JS_PUBLIC_API(void) JS_CallTenuredObjectTracer(JSTracer* trc, JS::TenuredHeap* objp, const char* name); @@ -348,8 +356,10 @@ TraceChildren(JSTracer* trc, GCCellPtr thing); typedef js::HashSet, js::SystemAllocPolicy> ZoneSet; } // namespace JS -// Trace every value within |zones| that is wrapped by a cross-compartment -// wrapper from a zone that is not an element of |zones|. +/** + * Trace every value within |zones| that is wrapped by a cross-compartment + * wrapper from a zone that is not an element of |zones|. + */ extern JS_PUBLIC_API(void) JS_TraceIncomingCCWs(JSTracer* trc, const JS::ZoneSet& zones); diff --git a/js/public/Value.h b/js/public/Value.h index 4fc2afb85c57..20a441ad3264 100644 --- a/js/public/Value.h +++ b/js/public/Value.h @@ -237,25 +237,60 @@ typedef uint64_t JSValueShiftedTag; typedef enum JSWhyMagic { - JS_ELEMENTS_HOLE, /* a hole in a native object's elements */ - JS_NO_ITER_VALUE, /* there is not a pending iterator value */ - JS_GENERATOR_CLOSING, /* exception value thrown when closing a generator */ - JS_NO_CONSTANT, /* compiler sentinel value */ - JS_THIS_POISON, /* used in debug builds to catch tracing errors */ - JS_ARG_POISON, /* used in debug builds to catch tracing errors */ - JS_SERIALIZE_NO_NODE, /* an empty subnode in the AST serializer */ - JS_LAZY_ARGUMENTS, /* lazy arguments value on the stack */ - JS_OPTIMIZED_ARGUMENTS, /* optimized-away 'arguments' value */ - JS_IS_CONSTRUCTING, /* magic value passed to natives to indicate construction */ - JS_OVERWRITTEN_CALLEE, /* arguments.callee has been overwritten */ - JS_BLOCK_NEEDS_CLONE, /* value of static block object slot */ - JS_HASH_KEY_EMPTY, /* see class js::HashableValue */ - JS_ION_ERROR, /* error while running Ion code */ - JS_ION_BAILOUT, /* missing recover instruction result */ - JS_OPTIMIZED_OUT, /* optimized out slot */ - JS_UNINITIALIZED_LEXICAL, /* uninitialized lexical bindings that produce ReferenceError - * on touch. */ - JS_GENERIC_MAGIC, /* for local use */ + /** a hole in a native object's elements */ + JS_ELEMENTS_HOLE, + + /** there is not a pending iterator value */ + JS_NO_ITER_VALUE, + + /** exception value thrown when closing a generator */ + JS_GENERATOR_CLOSING, + + /** compiler sentinel value */ + JS_NO_CONSTANT, + + /** used in debug builds to catch tracing errors */ + JS_THIS_POISON, + + /** used in debug builds to catch tracing errors */ + JS_ARG_POISON, + + /** an empty subnode in the AST serializer */ + JS_SERIALIZE_NO_NODE, + + /** lazy arguments value on the stack */ + JS_LAZY_ARGUMENTS, + + /** optimized-away 'arguments' value */ + JS_OPTIMIZED_ARGUMENTS, + + /** magic value passed to natives to indicate construction */ + JS_IS_CONSTRUCTING, + + /** arguments.callee has been overwritten */ + JS_OVERWRITTEN_CALLEE, + + /** value of static block object slot */ + JS_BLOCK_NEEDS_CLONE, + + /** see class js::HashableValue */ + JS_HASH_KEY_EMPTY, + + /** error while running Ion code */ + JS_ION_ERROR, + + /** missing recover instruction result */ + JS_ION_BAILOUT, + + /** optimized out slot */ + JS_OPTIMIZED_OUT, + + /** uninitialized lexical bindings that produce ReferenceError on touch. */ + JS_UNINITIALIZED_LEXICAL, + + /** for local use */ + JS_GENERIC_MAGIC, + JS_WHY_MAGIC_COUNT } JSWhyMagic; @@ -967,7 +1002,7 @@ CanonicalizeNaN(double d) # pragma optimize("", on) #endif -/* +/** * JS::Value is the interface for a single JavaScript Engine value. A few * general notes on JS::Value: * @@ -1682,7 +1717,7 @@ template <> struct GCMethods template class MutableValueOperations; -/* +/** * A class designed for CRTP use in implementing the non-mutating parts of the * Value interface in Value-like classes. Outer must be a class inheriting * ValueOperations with a visible get() method returning a const @@ -1736,7 +1771,7 @@ class ValueOperations uint32_t magicUint32() const { return value().magicUint32(); } }; -/* +/** * A class designed for CRTP use in implementing all the mutating parts of the * Value interface in Value-like classes. Outer must be a class inheriting * MutableValueOperations with visible get() methods returning const and diff --git a/js/src/jsapi.h b/js/src/jsapi.h index 9959c4626f7f..f1b9a381d151 100644 --- a/js/src/jsapi.h +++ b/js/src/jsapi.h @@ -65,7 +65,7 @@ class JS_PUBLIC_API(AutoCheckRequestDepth) #endif /* JS_DEBUG */ -/* AutoValueArray roots an internal fixed-size array of Values. */ +/** AutoValueArray roots an internal fixed-size array of Values. */ template class MOZ_RAII AutoValueArray : public AutoGCRooter { @@ -457,7 +457,7 @@ class MOZ_RAII AutoHashSetRooter : protected AutoGCRooter MOZ_DECL_USE_GUARD_OBJECT_NOTIFIER }; -/* +/** * Custom rooting behavior for internal and external clients. */ class MOZ_RAII JS_PUBLIC_API(CustomAutoRooter) : private AutoGCRooter @@ -473,14 +473,14 @@ class MOZ_RAII JS_PUBLIC_API(CustomAutoRooter) : private AutoGCRooter friend void AutoGCRooter::trace(JSTracer* trc); protected: - /* Supplied by derived class to trace roots. */ + /** Supplied by derived class to trace roots. */ virtual void trace(JSTracer* trc) = 0; private: MOZ_DECL_USE_GUARD_OBJECT_NOTIFIER }; -/* A handle to an array of rooted values. */ +/** A handle to an array of rooted values. */ class HandleValueArray { const size_t length_; @@ -497,10 +497,10 @@ class HandleValueArray template MOZ_IMPLICIT HandleValueArray(const AutoValueArray& values) : length_(N), elements_(values.begin()) {} - /* CallArgs must already be rooted somewhere up the stack. */ + /** CallArgs must already be rooted somewhere up the stack. */ MOZ_IMPLICIT HandleValueArray(const JS::CallArgs& args) : length_(args.length()), elements_(args.array()) {} - /* Use with care! Only call this if the data is guaranteed to be marked. */ + /** Use with care! Only call this if the data is guaranteed to be marked. */ static HandleValueArray fromMarkedLocation(size_t len, const Value* elements) { return HandleValueArray(len, elements); } @@ -550,7 +550,7 @@ typedef enum JSContextOp { JSCONTEXT_DESTROY } JSContextOp; -/* +/** * The possible values for contextOp when the runtime calls the callback are: * JSCONTEXT_NEW JS_NewContext successfully created a new JSContext * instance. The callback can initialize the instance as @@ -575,14 +575,14 @@ typedef void (* JSGCCallback)(JSRuntime* rt, JSGCStatus status, void* data); typedef enum JSFinalizeStatus { - /* + /** * Called when preparing to sweep a group of compartments, before anything * has been swept. The collector will not yield to the mutator before * calling the callback with JSFINALIZE_GROUP_END status. */ JSFINALIZE_GROUP_START, - /* + /** * Called when preparing to sweep a group of compartments. Weak references * to unmarked things have been removed and things that are not swept * incrementally have been finalized at this point. The collector may yield @@ -590,7 +590,7 @@ typedef enum JSFinalizeStatus { */ JSFINALIZE_GROUP_END, - /* + /** * Called at the end of collection when everything has been swept. */ JSFINALIZE_COLLECTION_END @@ -608,7 +608,7 @@ typedef bool typedef void (* JSErrorReporter)(JSContext* cx, const char* message, JSErrorReport* report); -/* +/** * Possible exception types. These types are part of a JSErrorFormatString * structure. They define which error to throw in case of a runtime error. * JSEXN_NONE marks an unthrowable error. @@ -627,13 +627,13 @@ typedef enum JSExnType { } JSExnType; typedef struct JSErrorFormatString { - /* The error format string in ASCII. */ + /** The error format string in ASCII. */ const char* format; - /* The number of arguments to expand in the formatted error message. */ + /** The number of arguments to expand in the formatted error message. */ uint16_t argCount; - /* One of the JSExnType constants above. */ + /** One of the JSExnType constants above. */ int16_t exnType; } JSErrorFormatString; @@ -653,7 +653,7 @@ typedef bool typedef bool (* JSLocaleToUnicode)(JSContext* cx, const char* src, JS::MutableHandleValue rval); -/* +/** * Callback used to ask the embedding for the cross compartment wrapper handler * that implements the desired prolicy for this kind of object in the * destination compartment. |obj| is the object to be wrapped. If |existing| is @@ -665,7 +665,7 @@ typedef bool typedef JSObject* (* JSWrapObjectCallback)(JSContext* cx, JS::HandleObject existing, JS::HandleObject obj); -/* +/** * Callback used by the wrap hook to ask the embedding to prepare an object * for wrapping in a context. This might include unwrapping other wrappers * or even finding a more suitable object for the new compartment. @@ -721,26 +721,27 @@ JS_StringHasBeenPinned(JSContext* cx, JSString* str); namespace JS { -// Container class for passing in script source buffers to the JS engine. This -// not only groups the buffer and length values, it also provides a way to -// optionally pass ownership of the buffer to the JS engine without copying. -// Rules for use: -// -// 1) The data array must be allocated with js_malloc() or js_realloc() if -// ownership is being granted to the SourceBufferHolder. -// 2) If ownership is not given to the SourceBufferHolder, then the memory -// must be kept alive until the JS compilation is complete. -// 3) Any code calling SourceBufferHolder::take() must guarantee to keep the -// memory alive until JS compilation completes. Normally only the JS -// engine should be calling take(). -// -// Example use: -// -// size_t length = 512; -// char16_t* chars = static_cast(js_malloc(sizeof(char16_t) * length)); -// JS::SourceBufferHolder srcBuf(chars, length, JS::SourceBufferHolder::GiveOwnership); -// JS::Compile(cx, options, srcBuf); -// +/** + * Container class for passing in script source buffers to the JS engine. This + * not only groups the buffer and length values, it also provides a way to + * optionally pass ownership of the buffer to the JS engine without copying. + * Rules for use: + * + * 1) The data array must be allocated with js_malloc() or js_realloc() if + * ownership is being granted to the SourceBufferHolder. + * 2) If ownership is not given to the SourceBufferHolder, then the memory + * must be kept alive until the JS compilation is complete. + * 3) Any code calling SourceBufferHolder::take() must guarantee to keep the + * memory alive until JS compilation completes. Normally only the JS + * engine should be calling take(). + * + * Example use: + * + * size_t length = 512; + * char16_t* chars = static_cast(js_malloc(sizeof(char16_t) * length)); + * JS::SourceBufferHolder srcBuf(chars, length, JS::SourceBufferHolder::GiveOwnership); + * JS::Compile(cx, options, srcBuf); + */ class MOZ_STACK_CLASS SourceBufferHolder final { public: @@ -891,7 +892,7 @@ class MOZ_STACK_CLASS SourceBufferHolder final specified when passed to Object.defineProperty from script. */ -/* +/** * The first call to JS_CallOnce by any thread in a process will call 'func'. * Later calls to JS_CallOnce with the same JSCallOnceType object will be * suppressed. @@ -902,11 +903,11 @@ class MOZ_STACK_CLASS SourceBufferHolder final extern JS_PUBLIC_API(bool) JS_CallOnce(JSCallOnceType* once, JSInitCallback func); -/* Microseconds since the epoch, midnight, January 1, 1970 UTC. */ +/** Microseconds since the epoch, midnight, January 1, 1970 UTC. */ extern JS_PUBLIC_API(int64_t) JS_Now(void); -/* Don't want to export data, so provide accessors for non-inline Values. */ +/** Don't want to export data, so provide accessors for non-inline Values. */ extern JS_PUBLIC_API(JS::Value) JS_GetNaNValue(JSContext* cx); @@ -949,11 +950,11 @@ JS_LooselyEqual(JSContext* cx, JS::Handle v1, JS::Handle v extern JS_PUBLIC_API(bool) JS_SameValue(JSContext* cx, JS::Handle v1, JS::Handle v2, bool* same); -/* True iff fun is the global eval function. */ +/** True iff fun is the global eval function. */ extern JS_PUBLIC_API(bool) JS_IsBuiltinEvalFunction(JSFunction* fun); -/* True iff fun is the Function constructor. */ +/** True iff fun is the Function constructor. */ extern JS_PUBLIC_API(bool) JS_IsBuiltinFunctionConstructor(JSFunction* fun); @@ -1018,14 +1019,16 @@ typedef void* (*JS_ICUAllocFn)(const void*, size_t size); typedef void* (*JS_ICUReallocFn)(const void*, void* p, size_t size); typedef void (*JS_ICUFreeFn)(const void*, void* p); -// This function can be used to track memory used by ICU. -// Do not use it unless you know what you are doing! +/** + * This function can be used to track memory used by ICU. + * Do not use it unless you know what you are doing! + */ extern JS_PUBLIC_API(bool) JS_SetICUMemoryFunctions(JS_ICUAllocFn allocFn, JS_ICUReallocFn reallocFn, JS_ICUFreeFn freeFn); typedef double (*JS_CurrentEmbedderTimeFunction)(); -/* +/** * The embedding can specify a time function that will be used in some * situations. The function can return the time however it likes; but * the norm is to return times in units of milliseconds since an @@ -1035,7 +1038,7 @@ typedef double (*JS_CurrentEmbedderTimeFunction)(); JS_PUBLIC_API(void) JS_SetCurrentEmbedderTimeFunction(JS_CurrentEmbedderTimeFunction timeFn); -/* +/** * Return the time as computed using the current time function, or a * suitable default if one has not been set. */ @@ -1128,12 +1131,14 @@ JS_ContextIterator(JSRuntime* rt, JSContext** iterp); extern JS_PUBLIC_API(JSVersion) JS_GetVersion(JSContext* cx); -// Mutate the version on the compartment. This is generally discouraged, but -// necessary to support the version mutation in the js and xpc shell command -// set. -// -// It would be nice to put this in jsfriendapi, but the linkage requirements -// of the shells make that impossible. +/** + * Mutate the version on the compartment. This is generally discouraged, but + * necessary to support the version mutation in the js and xpc shell command + * set. + * + * It would be nice to put this in jsfriendapi, but the linkage requirements + * of the shells make that impossible. + */ JS_PUBLIC_API(void) JS_SetVersionForCompartment(JSCompartment* compartment, JSVersion version); @@ -1455,7 +1460,7 @@ class MOZ_RAII JS_PUBLIC_API(JSAutoNullableCompartment) MOZ_DECL_USE_GUARD_OBJECT_NOTIFIER }; -/* NB: This API is infallible; a nullptr return value does not indicate error. */ +/** NB: This API is infallible; a nullptr return value does not indicate error. */ extern JS_PUBLIC_API(JSCompartment*) JS_EnterCompartment(JSContext* cx, JSObject* target); @@ -1464,7 +1469,7 @@ JS_LeaveCompartment(JSContext* cx, JSCompartment* oldCompartment); typedef void (*JSIterateCompartmentCallback)(JSRuntime* rt, void* data, JSCompartment* compartment); -/* +/** * This function calls |compartmentCallback| on every compartment. Beware that * there is no guarantee that the compartment will survive after the callback * returns. Also, barriers are disabled via the TraceSession. @@ -1473,7 +1478,7 @@ extern JS_PUBLIC_API(void) JS_IterateCompartments(JSRuntime* rt, void* data, JSIterateCompartmentCallback compartmentCallback); -/* +/** * Initialize standard JS class constructors, prototypes, and any top-level * functions and constants associated with the standard classes (e.g. isNaN * for Number). @@ -1483,7 +1488,7 @@ JS_IterateCompartments(JSRuntime* rt, void* data, extern JS_PUBLIC_API(bool) JS_InitStandardClasses(JSContext* cx, JS::Handle obj); -/* +/** * Resolve id, which must contain either a string or an int, to a standard * class name in obj if possible, defining the class's constructor and/or * prototype and storing true in *resolved. If id does not name a standard @@ -1538,28 +1543,28 @@ ProtoKeyToId(JSContext* cx, JSProtoKey key, JS::MutableHandleId idp); extern JS_PUBLIC_API(JSProtoKey) JS_IdToProtoKey(JSContext* cx, JS::HandleId id); -/* +/** * Returns the original value of |Function.prototype| from the global object in * which |forObj| was created. */ extern JS_PUBLIC_API(JSObject*) JS_GetFunctionPrototype(JSContext* cx, JS::HandleObject forObj); -/* +/** * Returns the original value of |Object.prototype| from the global object in * which |forObj| was created. */ extern JS_PUBLIC_API(JSObject*) JS_GetObjectPrototype(JSContext* cx, JS::HandleObject forObj); -/* +/** * Returns the original value of |Array.prototype| from the global object in * which |forObj| was created. */ extern JS_PUBLIC_API(JSObject*) JS_GetArrayPrototype(JSContext* cx, JS::HandleObject forObj); -/* +/** * Returns the original value of |Error.prototype| from the global * object of the current compartment of cx. */ @@ -1581,7 +1586,7 @@ JS_HasExtensibleLexicalScope(JSObject* obj); extern JS_PUBLIC_API(JSObject*) JS_ExtensibleLexicalScope(JSObject* obj); -/* +/** * May return nullptr, if |c| never had a global (e.g. the atoms compartment), * or if |c|'s global has been collected. */ @@ -1595,14 +1600,14 @@ CurrentGlobalOrNull(JSContext* cx); } // namespace JS -/* +/** * Add 'Reflect.parse', a SpiderMonkey extension, to the Reflect object on the * given global. */ extern JS_PUBLIC_API(bool) JS_InitReflectParse(JSContext* cx, JS::HandleObject global); -/* +/** * Add various profiling-related functions as properties of the given object. * Defined in builtin/Profilers.cpp. */ @@ -1614,14 +1619,14 @@ extern JS_PUBLIC_API(bool) JS_DefineDebuggerObject(JSContext* cx, JS::HandleObject obj); #ifdef JS_HAS_CTYPES -/* +/** * Initialize the 'ctypes' object on a global variable 'obj'. The 'ctypes' * object will be sealed. */ extern JS_PUBLIC_API(bool) JS_InitCTypesClass(JSContext* cx, JS::HandleObject global); -/* +/** * Convert a unicode string 'source' of length 'slen' to the platform native * charset, returning a null-terminated string allocated with JS_malloc. On * failure, this function should report an error. @@ -1629,7 +1634,7 @@ JS_InitCTypesClass(JSContext* cx, JS::HandleObject global); typedef char* (* JSCTypesUnicodeToNativeFun)(JSContext* cx, const char16_t* source, size_t slen); -/* +/** * Set of function pointers that ctypes can use for various internal functions. * See JS_SetCTypesCallbacks below. Providing nullptr for a function is safe, * and will result in the applicable ctypes functionality not being available. @@ -1640,7 +1645,7 @@ struct JSCTypesCallbacks { typedef struct JSCTypesCallbacks JSCTypesCallbacks; -/* +/** * Set the callbacks on the provided 'ctypesObj' object. 'callbacks' should be a * pointer to static data that exists for the lifetime of 'ctypesObj', but it * may safely be altered after calling this function and without having @@ -1656,7 +1661,7 @@ JS_malloc(JSContext* cx, size_t nbytes); extern JS_PUBLIC_API(void*) JS_realloc(JSContext* cx, void* p, size_t oldBytes, size_t newBytes); -/* +/** * A wrapper for js_free(p) that may delay js_free(p) invocation as a * performance optimization. * cx may be nullptr. @@ -1664,7 +1669,7 @@ JS_realloc(JSContext* cx, void* p, size_t oldBytes, size_t newBytes); extern JS_PUBLIC_API(void) JS_free(JSContext* cx, void* p); -/* +/** * A wrapper for js_free(p) that may delay js_free(p) invocation as a * performance optimization as specified by the given JSFreeOp instance. */ @@ -1680,11 +1685,11 @@ JS_updateMallocCounter(JSContext* cx, size_t nbytes); extern JS_PUBLIC_API(char*) JS_strdup(JSContext* cx, const char* s); -/* Duplicate a string. Does not report an error on failure. */ +/** Duplicate a string. Does not report an error on failure. */ extern JS_PUBLIC_API(char*) JS_strdup(JSRuntime* rt, const char* s); -/* +/** * Register externally maintained GC roots. * * traceOp: the trace operation. For each root the implementation should call @@ -1694,7 +1699,7 @@ JS_strdup(JSRuntime* rt, const char* s); extern JS_PUBLIC_API(bool) JS_AddExtraGCRootsTracer(JSRuntime* rt, JSTraceDataOp traceOp, void* data); -/* Undo a call to JS_AddExtraGCRootsTracer. */ +/** Undo a call to JS_AddExtraGCRootsTracer. */ extern JS_PUBLIC_API(void) JS_RemoveExtraGCRootsTracer(JSRuntime* rt, JSTraceDataOp traceOp, void* data); @@ -1754,86 +1759,86 @@ extern JS_PUBLIC_API(void) JS_UpdateWeakPointerAfterGCUnbarriered(JSObject** objp); typedef enum JSGCParamKey { - /* Maximum nominal heap before last ditch GC. */ + /** Maximum nominal heap before last ditch GC. */ JSGC_MAX_BYTES = 0, - /* Number of JS_malloc bytes before last ditch GC. */ + /** Number of JS_malloc bytes before last ditch GC. */ JSGC_MAX_MALLOC_BYTES = 1, - /* Amount of bytes allocated by the GC. */ + /** Amount of bytes allocated by the GC. */ JSGC_BYTES = 3, - /* Number of times GC has been invoked. Includes both major and minor GC. */ + /** Number of times GC has been invoked. Includes both major and minor GC. */ JSGC_NUMBER = 4, - /* Max size of the code cache in bytes. */ + /** Max size of the code cache in bytes. */ JSGC_MAX_CODE_CACHE_BYTES = 5, - /* Select GC mode. */ + /** Select GC mode. */ JSGC_MODE = 6, - /* Number of cached empty GC chunks. */ + /** Number of cached empty GC chunks. */ JSGC_UNUSED_CHUNKS = 7, - /* Total number of allocated GC chunks. */ + /** Total number of allocated GC chunks. */ JSGC_TOTAL_CHUNKS = 8, - /* Max milliseconds to spend in an incremental GC slice. */ + /** Max milliseconds to spend in an incremental GC slice. */ JSGC_SLICE_TIME_BUDGET = 9, - /* Maximum size the GC mark stack can grow to. */ + /** Maximum size the GC mark stack can grow to. */ JSGC_MARK_STACK_LIMIT = 10, - /* + /** * GCs less than this far apart in time will be considered 'high-frequency GCs'. * See setGCLastBytes in jsgc.cpp. */ JSGC_HIGH_FREQUENCY_TIME_LIMIT = 11, - /* Start of dynamic heap growth. */ + /** Start of dynamic heap growth. */ JSGC_HIGH_FREQUENCY_LOW_LIMIT = 12, - /* End of dynamic heap growth. */ + /** End of dynamic heap growth. */ JSGC_HIGH_FREQUENCY_HIGH_LIMIT = 13, - /* Upper bound of heap growth. */ + /** Upper bound of heap growth. */ JSGC_HIGH_FREQUENCY_HEAP_GROWTH_MAX = 14, - /* Lower bound of heap growth. */ + /** Lower bound of heap growth. */ JSGC_HIGH_FREQUENCY_HEAP_GROWTH_MIN = 15, - /* Heap growth for low frequency GCs. */ + /** Heap growth for low frequency GCs. */ JSGC_LOW_FREQUENCY_HEAP_GROWTH = 16, - /* + /** * If false, the heap growth factor is fixed at 3. If true, it is determined * based on whether GCs are high- or low- frequency. */ JSGC_DYNAMIC_HEAP_GROWTH = 17, - /* If true, high-frequency GCs will use a longer mark slice. */ + /** If true, high-frequency GCs will use a longer mark slice. */ JSGC_DYNAMIC_MARK_SLICE = 18, - /* Lower limit after which we limit the heap growth. */ + /** Lower limit after which we limit the heap growth. */ JSGC_ALLOCATION_THRESHOLD = 19, - /* + /** * We decommit memory lazily. If more than this number of megabytes is * available to be decommitted, then JS_MaybeGC will trigger a shrinking GC * to decommit it. */ JSGC_DECOMMIT_THRESHOLD = 20, - /* + /** * We try to keep at least this many unused chunks in the free chunk pool at * all times, even after a shrinking GC. */ JSGC_MIN_EMPTY_CHUNK_COUNT = 21, - /* We never keep more than this many unused chunks in the free chunk pool. */ + /** We never keep more than this many unused chunks in the free chunk pool. */ JSGC_MAX_EMPTY_CHUNK_COUNT = 22, - /* Whether compacting GC is enabled. */ + /** Whether compacting GC is enabled. */ JSGC_COMPACTING_ENABLED = 23 } JSGCParamKey; @@ -1852,7 +1857,7 @@ JS_GetGCParameterForThread(JSContext* cx, JSGCParamKey key); extern JS_PUBLIC_API(void) JS_SetGCParametersBasedOnAvailableMemory(JSRuntime* rt, uint32_t availMem); -/* +/** * Create a new JSString whose chars member refers to external memory, i.e., * memory requiring application-specific finalization. */ @@ -1860,20 +1865,20 @@ extern JS_PUBLIC_API(JSString*) JS_NewExternalString(JSContext* cx, const char16_t* chars, size_t length, const JSStringFinalizer* fin); -/* +/** * Return whether 'str' was created with JS_NewExternalString or * JS_NewExternalStringWithClosure. */ extern JS_PUBLIC_API(bool) JS_IsExternalString(JSString* str); -/* +/** * Return the 'fin' arg passed to JS_NewExternalString. */ extern JS_PUBLIC_API(const JSStringFinalizer*) JS_GetExternalStringFinalizer(JSString* str); -/* +/** * Set the size of the native stack that should not be exceed. To disable * stack size checking pass 0. * @@ -1952,7 +1957,7 @@ typedef JSConstScalarSpec JSConstIntegerSpec; struct JSJitInfo; -/* +/** * Wrapper to relace JSNative for JSPropertySpecs and JSFunctionSpecs. This will * allow us to pass one JSJitInfo per function with the property/function spec, * without additional field overhead. @@ -1968,7 +1973,7 @@ typedef struct JSNativeWrapper { */ #define JSNATIVE_WRAPPER(native) { {native, nullptr} } -/* +/** * Description of a property. JS_DefineProperties and JS_InitClass take arrays * of these and define many properties at once. JS_PSG, JS_PSGS and JS_PS_END * are helper macros for defining such arrays. @@ -2100,7 +2105,7 @@ inline int CheckIsSetterOp(JSSetterOp op); { { nullptr, JS_CAST_STRING_TO(getterName, const JSJitInfo*) } }, \ JSNATIVE_WRAPPER(nullptr) } -/* +/** * To define a native function, set call to a JSNativeWrapper. To define a * self-hosted function, set selfHostedName to the name of a function * compiled during JSRuntime::initSelfHosting. @@ -2159,7 +2164,7 @@ JS_InitClass(JSContext* cx, JS::HandleObject obj, JS::HandleObject parent_proto, const JSPropertySpec* ps, const JSFunctionSpec* fs, const JSPropertySpec* static_ps, const JSFunctionSpec* static_fs); -/* +/** * Set up ctor.prototype = proto and proto.constructor = ctor with the * right property flags. */ @@ -2362,26 +2367,28 @@ CompartmentOptionsRef(JSObject* obj); JS_PUBLIC_API(CompartmentOptions&) CompartmentOptionsRef(JSContext* cx); -// During global creation, we fire notifications to callbacks registered -// via the Debugger API. These callbacks are arbitrary script, and can touch -// the global in arbitrary ways. When that happens, the global should not be -// in a half-baked state. But this creates a problem for consumers that need -// to set slots on the global to put it in a consistent state. -// -// This API provides a way for consumers to set slots atomically (immediately -// after the global is created), before any debugger hooks are fired. It's -// unfortunately on the clunky side, but that's the way the cookie crumbles. -// -// If callers have no additional state on the global to set up, they may pass -// |FireOnNewGlobalHook| to JS_NewGlobalObject, which causes that function to -// fire the hook as its final act before returning. Otherwise, callers should -// pass |DontFireOnNewGlobalHook|, which means that they are responsible for -// invoking JS_FireOnNewGlobalObject upon successfully creating the global. If -// an error occurs and the operation aborts, callers should skip firing the -// hook. But otherwise, callers must take care to fire the hook exactly once -// before compiling any script in the global's scope (we have assertions in -// place to enforce this). This lets us be sure that debugger clients never miss -// breakpoints. +/** + * During global creation, we fire notifications to callbacks registered + * via the Debugger API. These callbacks are arbitrary script, and can touch + * the global in arbitrary ways. When that happens, the global should not be + * in a half-baked state. But this creates a problem for consumers that need + * to set slots on the global to put it in a consistent state. + * + * This API provides a way for consumers to set slots atomically (immediately + * after the global is created), before any debugger hooks are fired. It's + * unfortunately on the clunky side, but that's the way the cookie crumbles. + * + * If callers have no additional state on the global to set up, they may pass + * |FireOnNewGlobalHook| to JS_NewGlobalObject, which causes that function to + * fire the hook as its final act before returning. Otherwise, callers should + * pass |DontFireOnNewGlobalHook|, which means that they are responsible for + * invoking JS_FireOnNewGlobalObject upon successfully creating the global. If + * an error occurs and the operation aborts, callers should skip firing the + * hook. But otherwise, callers must take care to fire the hook exactly once + * before compiling any script in the global's scope (we have assertions in + * place to enforce this). This lets us be sure that debugger clients never miss + * breakpoints. + */ enum OnNewGlobalHookOption { FireOnNewGlobalHook, DontFireOnNewGlobalHook @@ -2393,7 +2400,7 @@ extern JS_PUBLIC_API(JSObject*) JS_NewGlobalObject(JSContext* cx, const JSClass* clasp, JSPrincipals* principals, JS::OnNewGlobalHookOption hookOption, const JS::CompartmentOptions& options = JS::CompartmentOptions()); -/* +/** * Spidermonkey does not have a good way of keeping track of what compartments should be marked on * their own. We can mark the roots unconditionally, but marking GC things only relevant in live * compartments is hard. To mitigate this, we create a static trace hook, installed on each global @@ -2417,18 +2424,18 @@ JS_IsNative(JSObject* obj); extern JS_PUBLIC_API(JSRuntime*) JS_GetObjectRuntime(JSObject* obj); -/* +/** * Unlike JS_NewObject, JS_NewObjectWithGivenProto does not compute a default * proto. If proto is nullptr, the JS object will have `null` as [[Prototype]]. */ extern JS_PUBLIC_API(JSObject*) JS_NewObjectWithGivenProto(JSContext* cx, const JSClass* clasp, JS::Handle proto); -// Creates a new plain object, like `new Object()`, with Object.prototype as [[Prototype]]. +/** Creates a new plain object, like `new Object()`, with Object.prototype as [[Prototype]]. */ extern JS_PUBLIC_API(JSObject*) JS_NewPlainObject(JSContext* cx); -/* +/** * Freeze obj, and all objects it refers to, recursively. This will not recurse * through non-extensible objects, on the assumption that those are already * deep-frozen. @@ -2436,7 +2443,7 @@ JS_NewPlainObject(JSContext* cx); extern JS_PUBLIC_API(bool) JS_DeepFreezeObject(JSContext* cx, JS::Handle obj); -/* +/** * Freezes an object; see ES5's Object.freeze(obj) method. */ extern JS_PUBLIC_API(bool) @@ -3324,19 +3331,23 @@ JS_NewArrayObject(JSContext* cx, const JS::HandleValueArray& contents); extern JS_PUBLIC_API(JSObject*) JS_NewArrayObject(JSContext* cx, size_t length); -// Returns true and sets |*isArray| indicating whether |value| is an Array -// object or a wrapper around one, otherwise returns false on failure. -// -// This method returns true with |*isArray == false| when passed a proxy whose -// target is an Array, or when passed a revoked proxy. +/** + * Returns true and sets |*isArray| indicating whether |value| is an Array + * object or a wrapper around one, otherwise returns false on failure. + * + * This method returns true with |*isArray == false| when passed a proxy whose + * target is an Array, or when passed a revoked proxy. + */ extern JS_PUBLIC_API(bool) JS_IsArrayObject(JSContext* cx, JS::HandleValue value, bool* isArray); -// Returns true and sets |*isArray| indicating whether |obj| is an Array object -// or a wrapper around one, otherwise returns false on failure. -// -// This method returns true with |*isArray == false| when passed a proxy whose -// target is an Array, or when passed a revoked proxy. +/** + * Returns true and sets |*isArray| indicating whether |obj| is an Array object + * or a wrapper around one, otherwise returns false on failure. + * + * This method returns true with |*isArray == false| when passed a proxy whose + * target is an Array, or when passed a revoked proxy. + */ extern JS_PUBLIC_API(bool) JS_IsArrayObject(JSContext* cx, JS::HandleObject obj, bool* isArray); @@ -3346,14 +3357,14 @@ JS_GetArrayLength(JSContext* cx, JS::Handle obj, uint32_t* lengthp); extern JS_PUBLIC_API(bool) JS_SetArrayLength(JSContext* cx, JS::Handle obj, uint32_t length); -/* +/** * Assign 'undefined' to all of the object's non-reserved slots. Note: this is * done for all slots, regardless of the associated property descriptor. */ JS_PUBLIC_API(void) JS_SetAllNonReservedSlotsToUndefined(JSContext* cx, JSObject* objArg); -/* +/** * Create a new array buffer with the given contents. It must be legal to pass * these contents to free(). On success, the ownership is transferred to the * new array buffer. @@ -3361,7 +3372,7 @@ JS_SetAllNonReservedSlotsToUndefined(JSContext* cx, JSObject* objArg); extern JS_PUBLIC_API(JSObject*) JS_NewArrayBufferWithContents(JSContext* cx, size_t nbytes, void* contents); -/* +/** * Steal the contents of the given array buffer. The array buffer has its * length set to 0 and its contents array cleared. The caller takes ownership * of the return value and must free it or transfer ownership via @@ -3370,7 +3381,7 @@ JS_NewArrayBufferWithContents(JSContext* cx, size_t nbytes, void* contents); extern JS_PUBLIC_API(void*) JS_StealArrayBufferContents(JSContext* cx, JS::HandleObject obj); -/* +/** * Create a new mapped array buffer with the given memory mapped contents. It * must be legal to free the contents pointer by unmapping it. On success, * ownership is transferred to the new mapped array buffer. @@ -3378,14 +3389,14 @@ JS_StealArrayBufferContents(JSContext* cx, JS::HandleObject obj); extern JS_PUBLIC_API(JSObject*) JS_NewMappedArrayBufferWithContents(JSContext* cx, size_t nbytes, void* contents); -/* +/** * Create memory mapped array buffer contents. * Caller must take care of closing fd after calling this function. */ extern JS_PUBLIC_API(void*) JS_CreateMappedArrayBufferContents(int fd, size_t offset, size_t length); -/* +/** * Release the allocated resource of mapped array buffer contents before the * object is created. * If a new object has been created by JS_NewMappedArrayBufferWithContents() @@ -3433,7 +3444,7 @@ NewFunctionFromSpec(JSContext* cx, const JSFunctionSpec* fs, HandleId id); extern JS_PUBLIC_API(JSObject*) JS_GetFunctionObject(JSFunction* fun); -/* +/** * Return the function's identifier as a JSString, or null if fun is unnamed. * The returned string lives as long as fun, so you don't need to root a saved * reference to it if fun is well-connected or rooted, and provided you bound @@ -3442,7 +3453,7 @@ JS_GetFunctionObject(JSFunction* fun); extern JS_PUBLIC_API(JSString*) JS_GetFunctionId(JSFunction* fun); -/* +/** * Return a function's display name. This is the defined name if one was given * where the function was defined, or it could be an inferred name by the JS * engine in the case that the function was defined to be anonymous. This can @@ -3458,7 +3469,7 @@ JS_GetFunctionDisplayId(JSFunction* fun); extern JS_PUBLIC_API(uint16_t) JS_GetFunctionArity(JSFunction* fun); -/* +/** * Infallible predicate to test whether obj is a function object (faster than * comparing obj's class name to "Function", but equivalent unless someone has * overwritten the "Function" identifier with a different constructor and then @@ -3470,13 +3481,15 @@ JS_ObjectIsFunction(JSContext* cx, JSObject* obj); extern JS_PUBLIC_API(bool) JS_IsNativeFunction(JSObject* funobj, JSNative call); -/* Return whether the given function is a valid constructor. */ +/** Return whether the given function is a valid constructor. */ extern JS_PUBLIC_API(bool) JS_IsConstructor(JSFunction* fun); -// This enum is used to select if properties with JSPROP_DEFINE_LATE flag -// should be defined on the object. -// Normal JSAPI consumers probably always want DefineAllProperties here. +/** + * This enum is used to select if properties with JSPROP_DEFINE_LATE flag + * should be defined on the object. + * Normal JSAPI consumers probably always want DefineAllProperties here. + */ enum PropertyDefinitionBehavior { DefineAllProperties, OnlyDefineLateProperties, @@ -3502,14 +3515,14 @@ JS_DefineFunctionById(JSContext* cx, JS::Handle obj, JS::Handle namespace JS { -/* +/** * Clone a top-level function into cx's global. This function will dynamically * fail if funobj was lexically nested inside some other function. */ extern JS_PUBLIC_API(JSObject*) CloneFunctionObject(JSContext* cx, HandleObject funobj); -/* +/** * As above, but providing an explicit scope chain. scopeChain must not include * the global object on it; that's implicit. It needs to contain the other * objects that should end up on the clone's scope chain. @@ -3519,7 +3532,7 @@ CloneFunctionObject(JSContext* cx, HandleObject funobj, AutoObjectVector& scopeC } // namespace JS -/* +/** * Given a buffer, return false if the buffer might become a valid * javascript statement with the addition of more lines. Otherwise return * true. The intent is to support interactive compilation - accumulate @@ -3530,7 +3543,7 @@ extern JS_PUBLIC_API(bool) JS_BufferIsCompilableUnit(JSContext* cx, JS::Handle obj, const char* utf8, size_t length); -/* +/** * |script| will always be set. On failure, it will be set to nullptr. */ extern JS_PUBLIC_API(bool) @@ -3538,7 +3551,7 @@ JS_CompileScript(JSContext* cx, const char* ascii, size_t length, const JS::CompileOptions& options, JS::MutableHandleScript script); -/* +/** * |script| will always be set. On failure, it will be set to nullptr. */ extern JS_PUBLIC_API(bool) @@ -3606,7 +3619,7 @@ namespace JS { * derived from ReadOnlyCompileOptions, so the compiler accepts it. */ -/* +/** * The common base class for the CompileOptions hierarchy. * * Use this in code that needs to propagate compile options from one compilation @@ -3700,7 +3713,7 @@ class JS_FRIEND_API(TransitiveCompileOptions) void operator=(const TransitiveCompileOptions&) = delete; }; -/* +/** * The class representing a full set of compile options. * * Use this in code that only needs to access compilation options created @@ -3749,7 +3762,7 @@ class JS_FRIEND_API(ReadOnlyCompileOptions) : public TransitiveCompileOptions void operator=(const ReadOnlyCompileOptions&) = delete; }; -/* +/** * Compilation options, with dynamic lifetime. An instance of this type * makes a copy of / holds / roots all dynamically allocated resources * (principals; elements; strings) that it refers to. Its destructor frees @@ -3839,7 +3852,7 @@ class JS_FRIEND_API(OwningCompileOptions) : public ReadOnlyCompileOptions void operator=(const CompileOptions& rhs) = delete; }; -/* +/** * Compilation options stored on the stack. An instance of this type * simply holds references to dynamically allocated resources (element; * filename; source map URL) that are owned by something else. If you @@ -3939,7 +3952,7 @@ class MOZ_STACK_CLASS JS_FRIEND_API(CompileOptions) : public ReadOnlyCompileOpti void operator=(const CompileOptions& rhs) = delete; }; -/* +/** * |script| will always be set. On failure, it will be set to nullptr. */ extern JS_PUBLIC_API(bool) @@ -4072,7 +4085,7 @@ JS_DecompileFunction(JSContext* cx, JS::Handle fun, unsigned indent * code can continue to use the familiar JS::Evaluate, etc., entry points. */ -/* +/** * Evaluate a script in the scope of the current global of cx. */ extern JS_PUBLIC_API(bool) @@ -4081,7 +4094,7 @@ JS_ExecuteScript(JSContext* cx, JS::HandleScript script, JS::MutableHandleValue extern JS_PUBLIC_API(bool) JS_ExecuteScript(JSContext* cx, JS::HandleScript script); -/* +/** * As above, but providing an explicit scope chain. scopeChain must not include * the global object on it; that's implicit. It needs to contain the other * objects that should end up on the script's scope chain. @@ -4095,7 +4108,7 @@ JS_ExecuteScript(JSContext* cx, JS::AutoObjectVector& scopeChain, JS::HandleScri namespace JS { -/* +/** * Like the above, but handles a cross-compartment script. If the script is * cross-compartment, it is cloned into the current compartment before executing. */ @@ -4106,14 +4119,14 @@ CloneAndExecuteScript(JSContext* cx, JS::Handle script); namespace JS { -/* +/** * Evaluate the given source buffer in the scope of the current global of cx. */ extern JS_PUBLIC_API(bool) Evaluate(JSContext* cx, const ReadOnlyCompileOptions& options, SourceBufferHolder& srcBuf, JS::MutableHandleValue rval); -/* +/** * As above, but providing an explicit scope chain. scopeChain must not include * the global object on it; that's implicit. It needs to contain the other * objects that should end up on the script's scope chain. @@ -4122,14 +4135,14 @@ extern JS_PUBLIC_API(bool) Evaluate(JSContext* cx, AutoObjectVector& scopeChain, const ReadOnlyCompileOptions& options, SourceBufferHolder& srcBuf, JS::MutableHandleValue rval); -/* +/** * Evaluate the given character buffer in the scope of the current global of cx. */ extern JS_PUBLIC_API(bool) Evaluate(JSContext* cx, const ReadOnlyCompileOptions& options, const char16_t* chars, size_t length, JS::MutableHandleValue rval); -/* +/** * As above, but providing an explicit scope chain. scopeChain must not include * the global object on it; that's implicit. It needs to contain the other * objects that should end up on the script's scope chain. @@ -4138,14 +4151,14 @@ extern JS_PUBLIC_API(bool) Evaluate(JSContext* cx, AutoObjectVector& scopeChain, const ReadOnlyCompileOptions& options, const char16_t* chars, size_t length, JS::MutableHandleValue rval); -/* +/** * Evaluate the given byte buffer in the scope of the current global of cx. */ extern JS_PUBLIC_API(bool) Evaluate(JSContext* cx, const ReadOnlyCompileOptions& options, const char* bytes, size_t length, JS::MutableHandleValue rval); -/* +/** * Evaluate the given file in the scope of the current global of cx. */ extern JS_PUBLIC_API(bool) @@ -4201,7 +4214,7 @@ JS_RestoreFrameChain(JSContext* cx); namespace JS { -/* +/** * This class can be used to store a pointer to the youngest frame of a saved * stack in the specified JSContext. This reference will be picked up by any new * calls performed until the class is destroyed, with the specified asyncCause, @@ -4345,7 +4358,7 @@ JS_GetStringLength(JSString* str); extern JS_PUBLIC_API(bool) JS_StringIsFlat(JSString* str); -/* Returns true iff the string's characters are stored as Latin1. */ +/** Returns true iff the string's characters are stored as Latin1. */ extern JS_PUBLIC_API(bool) JS_StringHasLatin1Chars(JSString* str); @@ -4408,7 +4421,7 @@ JS_FlatStringEqualsAscii(JSFlatString* str, const char* asciiBytes); extern JS_PUBLIC_API(size_t) JS_PutEscapedFlatString(char* buffer, size_t size, JSFlatString* str, char quote); -/* +/** * Create a dependent string, i.e., a string that owns no character storage, * but that refers to a slice of another string's chars. Dependent strings * are mutable by definition, so the thread safety comments above apply. @@ -4417,14 +4430,14 @@ extern JS_PUBLIC_API(JSString*) JS_NewDependentString(JSContext* cx, JS::HandleString str, size_t start, size_t length); -/* +/** * Concatenate two strings, possibly resulting in a rope. * See above for thread safety comments. */ extern JS_PUBLIC_API(JSString*) JS_ConcatStrings(JSContext* cx, JS::HandleString left, JS::HandleString right); -/* +/** * For JS_DecodeBytes, set *dstlenp to the size of the destination buffer before * the call; on return, *dstlenp contains the number of characters actually * stored. To determine the necessary destination buffer size, make a sizing @@ -4441,20 +4454,20 @@ JS_PUBLIC_API(bool) JS_DecodeBytes(JSContext* cx, const char* src, size_t srclen, char16_t* dst, size_t* dstlenp); -/* +/** * A variation on JS_EncodeCharacters where a null terminated string is * returned that you are expected to call JS_free on when done. */ JS_PUBLIC_API(char*) JS_EncodeString(JSContext* cx, JSString* str); -/* +/** * Same behavior as JS_EncodeString(), but encode into UTF-8 string */ JS_PUBLIC_API(char*) JS_EncodeStringToUTF8(JSContext* cx, JS::HandleString str); -/* +/** * Get number of bytes in the string encoding (without accounting for a * terminating zero bytes. The function returns (size_t) -1 if the string * can not be encoded into bytes and reports an error using cx accordingly. @@ -4462,7 +4475,7 @@ JS_EncodeStringToUTF8(JSContext* cx, JS::HandleString str); JS_PUBLIC_API(size_t) JS_GetStringEncodingLength(JSContext* cx, JSString* str); -/* +/** * Encode string into a buffer. The function does not stores an additional * zero byte. The function returns (size_t) -1 if the string can not be * encoded into bytes with no error reported. Otherwise it returns the number @@ -4564,7 +4577,7 @@ AddonIdOfObject(JSObject* obj); namespace JS { -/* +/** * Create a new Symbol with the given description. This function never returns * a Symbol that is in the Runtime-wide symbol registry. * @@ -4574,7 +4587,7 @@ namespace JS { JS_PUBLIC_API(Symbol*) NewSymbol(JSContext* cx, HandleString description); -/* +/** * Symbol.for as specified in ES6. * * Get a Symbol with the description 'key' from the Runtime-wide symbol registry. @@ -4584,7 +4597,7 @@ NewSymbol(JSContext* cx, HandleString description); JS_PUBLIC_API(Symbol*) GetSymbolFor(JSContext* cx, HandleString key); -/* +/** * Get the [[Description]] attribute of the given symbol. * * This function is infallible. If it returns null, that means the symbol's @@ -4606,7 +4619,7 @@ enum class SymbolCode : uint32_t { /* For use in loops that iterate over the well-known symbols. */ const size_t WellKnownSymbolLimit = 4; -/* +/** * Return the SymbolCode telling what sort of symbol `symbol` is. * * A symbol's SymbolCode never changes once it is created. @@ -4614,7 +4627,7 @@ const size_t WellKnownSymbolLimit = 4; JS_PUBLIC_API(SymbolCode) GetSymbolCode(Handle symbol); -/* +/** * Get one of the well-known symbols defined by ES6. A single set of well-known * symbols is shared by all compartments in a JSRuntime. * @@ -4623,7 +4636,7 @@ GetSymbolCode(Handle symbol); JS_PUBLIC_API(Symbol*) GetWellKnownSymbol(JSContext* cx, SymbolCode which); -/* +/** * Return true if the given JSPropertySpec::name or JSFunctionSpec::name value * is actually a symbol code and not a string. See JS_SYM_FN. */ @@ -4637,7 +4650,7 @@ PropertySpecNameIsSymbol(const char* name) JS_PUBLIC_API(bool) PropertySpecNameEqualsId(const char* name, HandleId id); -/* +/** * Create a jsid that does not need to be marked for GC. * * 'name' is a JSPropertySpec::name or JSFunctionSpec::name value. The @@ -4656,14 +4669,14 @@ PropertySpecNameToPermanentId(JSContext* cx, const char* name, jsid* idp); */ typedef bool (* JSONWriteCallback)(const char16_t* buf, uint32_t len, void* data); -/* +/** * JSON.stringify as specified by ES5. */ JS_PUBLIC_API(bool) JS_Stringify(JSContext* cx, JS::MutableHandleValue value, JS::HandleObject replacer, JS::HandleValue space, JSONWriteCallback callback, void* data); -/* +/** * JSON.parse as specified by ES5. */ JS_PUBLIC_API(bool) @@ -4682,7 +4695,7 @@ JS_ParseJSONWithReviver(JSContext* cx, JS::HandleString str, JS::HandleValue rev /************************************************************************/ -/* +/** * The default locale for the ECMAScript Internationalization API * (Intl.Collator, Intl.NumberFormat, Intl.DateTimeFormat). * Note that the Internationalization API encourages clients to @@ -4692,13 +4705,13 @@ JS_ParseJSONWithReviver(JSContext* cx, JS::HandleString str, JS::HandleValue rev extern JS_PUBLIC_API(bool) JS_SetDefaultLocale(JSRuntime* rt, const char* locale); -/* +/** * Reset the default locale to OS defaults. */ extern JS_PUBLIC_API(void) JS_ResetDefaultLocale(JSRuntime* rt); -/* +/** * Locale specific string conversion and error message callbacks. */ struct JSLocaleCallbacks { @@ -4708,14 +4721,14 @@ struct JSLocaleCallbacks { JSLocaleToUnicode localeToUnicode; }; -/* +/** * Establish locale callbacks. The pointer must persist as long as the * JSRuntime. Passing nullptr restores the default behaviour. */ extern JS_PUBLIC_API(void) JS_SetLocaleCallbacks(JSRuntime* rt, const JSLocaleCallbacks* callbacks); -/* +/** * Return the address of the current locale callbacks struct, which may * be nullptr. */ @@ -4732,7 +4745,7 @@ namespace JS { const uint16_t MaxNumErrorArguments = 10; }; -/* +/** * Report an exception represented by the sprintf-like conversion of format * and its arguments. This exception message string is passed to a pre-set * JSErrorReporter function (set by JS_SetErrorReporter). @@ -4765,7 +4778,7 @@ JS_ReportErrorNumberUCArray(JSContext* cx, JSErrorCallback errorCallback, void* userRef, const unsigned errorNumber, const char16_t** args); -/* +/** * As above, but report a warning instead (JSREPORT_IS_WARNING(report.flags)). * Return true if there was no error trying to issue the warning, and if the * warning was not converted into an error due to the JSOPTION_WERROR option @@ -4784,13 +4797,13 @@ JS_ReportErrorFlagsAndNumberUC(JSContext* cx, unsigned flags, JSErrorCallback errorCallback, void* userRef, const unsigned errorNumber, ...); -/* +/** * Complain when out of memory. */ extern JS_PUBLIC_API(void) JS_ReportOutOfMemory(JSContext* cx); -/* +/** * Complain when an allocation size overflows the maximum supported limit. */ extern JS_PUBLIC_API(void) @@ -4961,15 +4974,17 @@ SetForEach(JSContext *cx, HandleObject obj, HandleValue callbackFn, HandleValue extern JS_PUBLIC_API(JSObject*) JS_NewDateObject(JSContext* cx, int year, int mon, int mday, int hour, int min, int sec); -// Returns true and sets |*isDate| indicating whether |obj| is a Date object or -// a wrapper around one, otherwise returns false on failure. -// -// This method returns true with |*isDate == false| when passed a proxy whose -// target is a Date, or when passed a revoked proxy. +/** + * Returns true and sets |*isDate| indicating whether |obj| is a Date object or + * a wrapper around one, otherwise returns false on failure. + * + * This method returns true with |*isDate == false| when passed a proxy whose + * target is a Date, or when passed a revoked proxy. + */ extern JS_PUBLIC_API(bool) JS_ObjectIsDate(JSContext* cx, JS::HandleObject obj, bool* isDate); -/* +/** * Clears the cache of calculated local time from each Date object. * Call to propagate a system timezone change. */ @@ -5018,11 +5033,13 @@ extern JS_PUBLIC_API(bool) JS_ExecuteRegExpNoStatics(JSContext* cx, JS::HandleObject reobj, char16_t* chars, size_t length, size_t* indexp, bool test, JS::MutableHandleValue rval); -// Returns true and sets |*isRegExp| indicating whether |obj| is a RegExp -// object or a wrapper around one, otherwise returns false on failure. -// -// This method returns true with |*isRegExp == false| when passed a proxy whose -// target is a RegExp, or when passed a revoked proxy. +/** + * Returns true and sets |*isRegExp| indicating whether |obj| is a RegExp + * object or a wrapper around one, otherwise returns false on failure. + * + * This method returns true with |*isRegExp == false| when passed a proxy whose + * target is a RegExp, or when passed a revoked proxy. + */ extern JS_PUBLIC_API(bool) JS_ObjectIsRegExp(JSContext* cx, JS::HandleObject obj, bool* isRegExp); @@ -5051,7 +5068,7 @@ JS_ReportPendingException(JSContext* cx); namespace JS { -/* +/** * Save and later restore the current exception state of a given JSContext. * This is useful for implementing behavior in C++ that's like try/catch * or try/finally in JS. @@ -5116,7 +5133,7 @@ JS_RestoreExceptionState(JSContext* cx, JSExceptionState* state); extern JS_PUBLIC_API(void) JS_DropExceptionState(JSContext* cx, JSExceptionState* state); -/* +/** * If the given object is an exception object, the exception will have (or be * able to lazily create) an error report struct, and this function will return * the address of that struct. Otherwise, it returns nullptr. The lifetime @@ -5141,7 +5158,7 @@ JS_IsStopIteration(JS::Value v); extern JS_PUBLIC_API(intptr_t) JS_GetCurrentThread(); -/* +/** * A JS runtime always has an "owner thread". The owner thread is set when the * runtime is created (to the current thread) and practically all entry points * into the JS engine check that a runtime (or anything contained in the @@ -5156,7 +5173,7 @@ JS_AbortIfWrongThread(JSRuntime* rt); /************************************************************************/ -/* +/** * A constructor can request that the JS engine create a default new 'this' * object of the given class, using the callee to determine parentage and * [[Prototype]]. @@ -5210,13 +5227,13 @@ JS_SetGlobalJitCompilerOption(JSRuntime* rt, JSJitCompilerOption opt, uint32_t v extern JS_PUBLIC_API(int) JS_GetGlobalJitCompilerOption(JSRuntime* rt, JSJitCompilerOption opt); -/* +/** * Convert a uint32_t index into a jsid. */ extern JS_PUBLIC_API(bool) JS_IndexToId(JSContext* cx, uint32_t index, JS::MutableHandleId); -/* +/** * Convert chars into a jsid. * * |chars| may not be an index. @@ -5224,13 +5241,13 @@ JS_IndexToId(JSContext* cx, uint32_t index, JS::MutableHandleId); extern JS_PUBLIC_API(bool) JS_CharsToId(JSContext* cx, JS::TwoByteChars chars, JS::MutableHandleId); -/* +/** * Test if the given string is a valid ECMAScript identifier */ extern JS_PUBLIC_API(bool) JS_IsIdentifier(JSContext* cx, JS::HandleString str, bool* isIdentifier); -/* +/** * Test whether the given chars + length are a valid ECMAScript identifier. * This version is infallible, so just returns whether the chars are an * identifier. @@ -5240,7 +5257,7 @@ JS_IsIdentifier(const char16_t* chars, size_t length); namespace JS { -/* +/** * AutoFilename encapsulates a pointer to a C-string and keeps the C-string * alive for as long as the associated AutoFilename object is alive. */ @@ -5260,7 +5277,7 @@ class MOZ_STACK_CLASS JS_PUBLIC_API(AutoFilename) void reset(void* newScriptSource); }; -/* +/** * Return the current filename, line number and column number of the most * currently running frame. Returns true if a scripted frame was found, false * otherwise. @@ -5275,7 +5292,7 @@ DescribeScriptedCaller(JSContext* cx, AutoFilename* filename = nullptr, extern JS_PUBLIC_API(JSObject*) GetScriptedCallerGlobal(JSContext* cx); -/* +/** * Informs the JS engine that the scripted caller should be hidden. This can be * used by the embedding to maintain an override of the scripted caller in its * calculations, by hiding the scripted caller in the JS engine and pushing data @@ -5347,7 +5364,7 @@ typedef bool typedef void (* CloseAsmJSCacheEntryForReadOp)(size_t size, const uint8_t* memory, intptr_t handle); -/* The list of reasons why an asm.js module may not be stored in the cache. */ +/** The list of reasons why an asm.js module may not be stored in the cache. */ enum AsmJSCacheResult { AsmJSCache_MIN, @@ -5387,12 +5404,13 @@ typedef void typedef js::Vector BuildIdCharVector; -// Return the buildId (represented as a sequence of characters) associated with -// the currently-executing build. If the JS engine is embedded such that a -// single cache entry can be observed by different compiled versions of the JS -// engine, it is critical that the buildId shall change for each new build of -// the JS engine. - +/** + * Return the buildId (represented as a sequence of characters) associated with + * the currently-executing build. If the JS engine is embedded such that a + * single cache entry can be observed by different compiled versions of the JS + * engine, it is critical that the buildId shall change for each new build of + * the JS engine. + */ typedef bool (* BuildIdOp)(BuildIdCharVector* buildId); @@ -5408,7 +5426,7 @@ struct AsmJSCacheOps extern JS_PUBLIC_API(void) SetAsmJSCacheOps(JSRuntime* rt, const AsmJSCacheOps* callbacks); -/* +/** * Convenience class for imitating a JS level for-of loop. Typical usage: * * ForOfIterator it(cx); @@ -5458,7 +5476,7 @@ class MOZ_STACK_CLASS JS_PUBLIC_API(ForOfIterator) { AllowNonIterable }; - /* + /** * Initialize the iterator. If AllowNonIterable is passed then if getting * the @@iterator property from iterable returns undefined init() will just * return true instead of throwing. Callers must then check @@ -5467,13 +5485,13 @@ class MOZ_STACK_CLASS JS_PUBLIC_API(ForOfIterator) { bool init(JS::HandleValue iterable, NonIterableBehavior nonIterableBehavior = ThrowOnNonIterable); - /* + /** * Get the next value from the iterator. If false *done is true * after this call, do not examine val. */ bool next(JS::MutableHandleValue val, bool* done); - /* + /** * If initialized with throwOnNonCallable = false, check whether * the value is iterable. */ @@ -5487,7 +5505,7 @@ class MOZ_STACK_CLASS JS_PUBLIC_API(ForOfIterator) { }; -/* +/** * If a large allocation fails when calling pod_{calloc,realloc}CanGC, the JS * engine may call the large-allocation- failure callback, if set, to allow the * embedding to flush caches, possibly perform shrinking GCs, etc. to make some @@ -5500,7 +5518,7 @@ typedef void extern JS_PUBLIC_API(void) SetLargeAllocationFailureCallback(JSRuntime* rt, LargeAllocationFailureCallback afc, void* data); -/* +/** * Unlike the error reporter, which is only called if the exception for an OOM * bubbles up and is not caught, the OutOfMemoryCallback is called immediately * at the OOM site to allow the embedding to capture the current state of heap @@ -5518,7 +5536,7 @@ extern JS_PUBLIC_API(void) SetOutOfMemoryCallback(JSRuntime* rt, OutOfMemoryCallback cb, void* data); -/* +/** * Capture the current call stack as a chain of SavedFrame JSObjects, and set * |stackp| to the SavedFrame for the youngest stack frame, or nullptr if there * are no JS frames on the stack. If |maxFrameCount| is non-zero, capture at @@ -5558,26 +5576,26 @@ enum class SavedFrameResult { AccessDenied }; -/* +/** * Given a SavedFrame JSObject, get its source property. Defaults to the empty * string. */ extern JS_PUBLIC_API(SavedFrameResult) GetSavedFrameSource(JSContext* cx, HandleObject savedFrame, MutableHandleString sourcep); -/* +/** * Given a SavedFrame JSObject, get its line property. Defaults to 0. */ extern JS_PUBLIC_API(SavedFrameResult) GetSavedFrameLine(JSContext* cx, HandleObject savedFrame, uint32_t* linep); -/* +/** * Given a SavedFrame JSObject, get its column property. Defaults to 0. */ extern JS_PUBLIC_API(SavedFrameResult) GetSavedFrameColumn(JSContext* cx, HandleObject savedFrame, uint32_t* columnp); -/* +/** * Given a SavedFrame JSObject, get its functionDisplayName string, or nullptr * if SpiderMonkey was unable to infer a name for the captured frame's * function. Defaults to nullptr. @@ -5585,13 +5603,13 @@ GetSavedFrameColumn(JSContext* cx, HandleObject savedFrame, uint32_t* columnp); extern JS_PUBLIC_API(SavedFrameResult) GetSavedFrameFunctionDisplayName(JSContext* cx, HandleObject savedFrame, MutableHandleString namep); -/* +/** * Given a SavedFrame JSObject, get its asyncCause string. Defaults to nullptr. */ extern JS_PUBLIC_API(SavedFrameResult) GetSavedFrameAsyncCause(JSContext* cx, HandleObject savedFrame, MutableHandleString asyncCausep); -/* +/** * Given a SavedFrame JSObject, get its asyncParent SavedFrame object or nullptr * if there is no asyncParent. The `asyncParentp` out parameter is _NOT_ * guaranteed to be in the cx's compartment. Defaults to nullptr. @@ -5599,7 +5617,7 @@ GetSavedFrameAsyncCause(JSContext* cx, HandleObject savedFrame, MutableHandleStr extern JS_PUBLIC_API(SavedFrameResult) GetSavedFrameAsyncParent(JSContext* cx, HandleObject savedFrame, MutableHandleObject asyncParentp); -/* +/** * Given a SavedFrame JSObject, get its parent SavedFrame object or nullptr if * it is the oldest frame in the stack. The `parentp` out parameter is _NOT_ * guaranteed to be in the cx's compartment. Defaults to nullptr. @@ -5607,7 +5625,7 @@ GetSavedFrameAsyncParent(JSContext* cx, HandleObject savedFrame, MutableHandleOb extern JS_PUBLIC_API(SavedFrameResult) GetSavedFrameParent(JSContext* cx, HandleObject savedFrame, MutableHandleObject parentp); -/* +/** * Given a SavedFrame JSObject stack, stringify it in the same format as * Error.prototype.stack. The stringified stack out parameter is placed in the * cx's compartment. Defaults to the empty string. @@ -5631,9 +5649,11 @@ namespace js { class AutoStopwatch; -// Container for performance data -// All values are monotonic. -// All values are updated after running to completion. +/** + * Container for performance data + * All values are monotonic. + * All values are updated after running to completion. + */ struct PerformanceData { // Number of times we have spent at least 2^n consecutive // milliseconds executing code in this group. @@ -5682,16 +5702,18 @@ struct PerformanceData { } }; -// A group of compartments forming a single unit in terms of -// performance monitoring. -// -// Two compartments belong to the same group if either: -// - they are part of the same add-on; -// - they are part of the same webpage; -// - they are both system built-ins. -// -// This class is refcounted by instances of `JSCompartment`. -// Do not attempt to hold to a pointer to a `PerformanceGroup`. +/** + * A group of compartments forming a single unit in terms of + * performance monitoring. + * + * Two compartments belong to the same group if either: + * - they are part of the same add-on; + * - they are part of the same webpage; + * - they are both system built-ins. + * + * This class is refcounted by instances of `JSCompartment`. + * Do not attempt to hold to a pointer to a `PerformanceGroup`. + */ struct PerformanceGroup { // Performance data for this group. @@ -5798,13 +5820,13 @@ private: const bool isSharedGroup_; }; -// -// Each PerformanceGroupHolder handles: -// - a reference-counted indirection towards a PerformanceGroup shared -// by several compartments -// - a owned PerformanceGroup representing the performance of a single -// compartment. -// +/** + * Each PerformanceGroupHolder handles: + * - a reference-counted indirection towards a PerformanceGroup shared + * by several compartments + * - a owned PerformanceGroup representing the performance of a single + * compartment. + */ struct PerformanceGroupHolder { // Get the shared group. // On first call, this causes a single Hashtable lookup. @@ -5865,7 +5887,7 @@ FlushPerformanceMonitoring(JSRuntime*); extern JS_PUBLIC_API(void) ResetPerformanceMonitoring(JSRuntime*); -/** +/* * Turn on/off stopwatch-based CPU monitoring. * * `SetStopwatchIsMonitoringCPOW` or `SetStopwatchIsMonitoringJank` diff --git a/js/src/jsfriendapi.h b/js/src/jsfriendapi.h index 2f5e5127b29c..34bb7e5d4560 100644 --- a/js/src/jsfriendapi.h +++ b/js/src/jsfriendapi.h @@ -57,10 +57,12 @@ JS_SplicePrototype(JSContext* cx, JS::HandleObject obj, JS::HandleObject proto); extern JS_FRIEND_API(JSObject*) JS_NewObjectWithUniqueType(JSContext* cx, const JSClass* clasp, JS::HandleObject proto); -// Allocate an object in exactly the same way as JS_NewObjectWithGivenProto, but -// without invoking the metadata callback on it. This allows creation of -// internal bookkeeping objects that are guaranteed to not have metadata -// attached to them. +/** + * Allocate an object in exactly the same way as JS_NewObjectWithGivenProto, but + * without invoking the metadata callback on it. This allows creation of + * internal bookkeeping objects that are guaranteed to not have metadata + * attached to them. + */ extern JS_FRIEND_API(JSObject*) JS_NewObjectWithoutMetadata(JSContext* cx, const JSClass* clasp, JS::Handle proto); @@ -83,7 +85,7 @@ JS_NondeterministicGetWeakMapKeys(JSContext* cx, JS::HandleObject obj, JS::Mutab extern JS_FRIEND_API(unsigned) JS_PCToLineNumber(JSScript* script, jsbytecode* pc, unsigned* columnp = nullptr); -/* +/** * Determine whether the given object is backed by a DeadObjectProxy. * * Such objects hold no other objects (they have no outgoing reference edges) @@ -156,7 +158,7 @@ JS_ObjectToOuterObject(JSContext* cx, JS::HandleObject obj); extern JS_FRIEND_API(JSObject*) JS_CloneObject(JSContext* cx, JS::HandleObject obj, JS::HandleObject proto); -/* +/** * Copy the own properties of src to dst in a fast way. src and dst must both * be native and must be in the compartment of cx. They must have the same * class, the same parent, and the same prototype. Class reserved slots will @@ -241,13 +243,13 @@ DumpBacktrace(JSContext* cx); namespace JS { -// Exposed for DumpJSStack +/** Exposed for DumpJSStack */ extern JS_FRIEND_API(char*) FormatStackDump(JSContext* cx, char* buf, bool showArgs, bool showLocals, bool showThisProps); } // namespace JS -/* +/** * Copies all own properties from |obj| to |target|. |obj| must be a "native" * object (that is to say, normal-ish - not an Array or a Proxy). * @@ -417,7 +419,7 @@ extern JS_FRIEND_API(bool) proxy_GetElements(JSContext* cx, JS::HandleObject proxy, uint32_t begin, uint32_t end, ElementAdder* adder); -/* +/** * A class of objects that return source code on demand. * * When code is compiled with setSourceIsLazy(true), SpiderMonkey doesn't @@ -432,7 +434,7 @@ class SourceHook { public: virtual ~SourceHook() { } - /* + /** * Set |*src| and |*length| to refer to the source code for |filename|. * On success, the caller owns the buffer to which |*src| points, and * should use JS_free to free it. @@ -440,7 +442,7 @@ class SourceHook { virtual bool load(JSContext* cx, const char* filename, char16_t** src, size_t* length) = 0; }; -/* +/** * Have |rt| use |hook| to retrieve lazily-retrieved source code. See the * comments for SourceHook. The runtime takes ownership of the hook, and * will delete it when the runtime itself is deleted, or when a new hook is @@ -449,7 +451,7 @@ class SourceHook { extern JS_FRIEND_API(void) SetSourceHook(JSRuntime* rt, mozilla::UniquePtr hook); -/* Remove |rt|'s source hook, and return it. The caller now owns the hook. */ +/** Remove |rt|'s source hook, and return it. The caller now owns the hook. */ extern JS_FRIEND_API(mozilla::UniquePtr) ForgetSourceHook(JSRuntime* rt); @@ -464,7 +466,7 @@ typedef enum { IgnoreNurseryObjects } DumpHeapNurseryBehaviour; - /* + /** * Dump the complete object graph of heap-allocated things. * fp is the file for the dump output. */ @@ -524,7 +526,7 @@ GetWeakmapKeyDelegate(JSObject* key); JS_FRIEND_API(JS::TraceKind) GCThingTraceKind(void* thing); -/* +/** * Invoke cellCallback on every gray JS_OBJECT in the given zone. */ extern JS_FRIEND_API(void) @@ -566,9 +568,11 @@ public: static const uint32_t FIXED_SLOTS_SHIFT = 27; }; -// This layout is shared by all native objects. For non-native objects, the -// group may always be accessed safely, and other members may be as well, -// depending on the object's specific layout. +/** + * This layout is shared by all native objects. For non-native objects, the + * group may always be accessed safely, and other members may be as well, + * depending on the object's specific layout. + */ struct Object { shadow::ObjectGroup* group; shadow::Shape* shape; @@ -706,7 +710,7 @@ inline void AssertSameCompartment(JSObject* objA, JSObject* objB) {} JS_FRIEND_API(void) NotifyAnimationActivity(JSObject* obj); -/* +/** * Return the outermost enclosing function (script) of the scripted caller. * This function returns nullptr in several cases: * - no script is running on the context @@ -1059,12 +1063,14 @@ GetPCCountScriptSummary(JSContext* cx, size_t script); JS_FRIEND_API(JSString*) GetPCCountScriptContents(JSContext* cx, size_t script); -// Generate lcov trace file content for the current compartment, and allocate a -// new buffer and return the content in it, the size of the newly allocated -// content within the buffer would be set to the length out-param. -// -// In case of out-of-memory, this function returns nullptr and does not set any -// value to the length out-param. +/** + * Generate lcov trace file content for the current compartment, and allocate a + * new buffer and return the content in it, the size of the newly allocated + * content within the buffer would be set to the length out-param. + * + * In case of out-of-memory, this function returns nullptr and does not set any + * value to the length out-param. + */ JS_FRIEND_API(char*) GetCodeCoverageSummary(JSContext* cx, size_t* length); @@ -1074,7 +1080,7 @@ ContextHasOutstandingRequests(const JSContext* cx); typedef void (* ActivityCallback)(void* arg, bool active); -/* +/** * Sets a callback that is run whenever the runtime goes idle - the * last active request ceases - and begins activity - when it was * idle and a request begins. @@ -1099,7 +1105,7 @@ GetDOMCallbacks(JSRuntime* rt); extern JS_FRIEND_API(JSObject*) GetTestingFunctions(JSContext* cx); -/* +/** * Helper to convert FreeOp to JSFreeOp when the definition of FreeOp is not * available and the compiler does not know that FreeOp inherits from * JSFreeOp. @@ -1112,7 +1118,7 @@ CastToJSFreeOp(FreeOp* fop) /* Implemented in jsexn.cpp. */ -/* +/** * Get an error type name from a JSExnType constant. * Returns nullptr for invalid arguments and JSEXN_INTERNALERR */ @@ -1254,7 +1260,7 @@ inline bool DOMProxyIsShadowing(DOMProxyShadowsResult result) { /* Implemented in jsdate.cpp. */ -/* Detect whether the internal date value is NaN. */ +/** Detect whether the internal date value is NaN. */ extern JS_FRIEND_API(bool) DateIsValid(JSContext* cx, JS::HandleObject obj, bool* isValid); @@ -1265,7 +1271,7 @@ DateGetMsecSinceEpoch(JSContext* cx, JS::HandleObject obj, double* msecSinceEpoc /* Implemented in jscntxt.cpp. */ -/* +/** * Report an exception, which is currently realized as a printf-style format * string and its arguments. */ @@ -1285,7 +1291,7 @@ GetErrorMessage(void* userRef, const unsigned errorNumber); // AutoStableStringChars is here so we can use it in ErrorReport. It // should get moved out of here if we can manage it. See bug 1040316. -/* +/** * This class provides safe access to a string's chars across a GC. Once * we allocate strings and chars in the nursery (bug 903519), this class * will have to make a copy of the string's chars if they are allocated @@ -1354,8 +1360,10 @@ class MOZ_STACK_CLASS AutoStableStringChars void operator=(const AutoStableStringChars& other) = delete; }; -// Creates a string of the form |ErrorType: ErrorMessage| for a JSErrorReport, -// which generally matches the toString() behavior of an ErrorObject. +/** + * Creates a string of the form |ErrorType: ErrorMessage| for a JSErrorReport, + * which generally matches the toString() behavior of an ErrorObject. + */ extern JS_FRIEND_API(JSString*) ErrorReportToString(JSContext* cx, JSErrorReport* reportp); @@ -1428,7 +1436,7 @@ GetSCOffset(JSStructuredCloneWriter* writer); namespace Scalar { -/* +/** * Scalar types that can appear in typed arrays and typed objects. The enum * values must to be kept in sync with the JS_SCALARTYPEREPR_ constants, as * well as the TypedArrayObject::classes and TypedArrayObject::protoClasses @@ -1444,13 +1452,13 @@ enum Type { Float32, Float64, - /* + /** * Special type that is a uint8_t, but assignments are clamped to [0, 256). * Treat the raw data type as a uint8_t. */ Uint8Clamped, - /* + /** * SIMD types don't have their own TypedArray equivalent, for now. */ MaxTypedArrayViewType, @@ -1687,19 +1695,19 @@ extern JS_FRIEND_API(JSObject*) JS_NewSharedFloat64ArrayWithBuffer(JSContext* cx, JS::HandleObject arrayBuffer, uint32_t byteOffset, uint32_t length); -/* +/** * Create a new SharedArrayBuffer with the given byte length. */ extern JS_FRIEND_API(JSObject*) JS_NewSharedArrayBuffer(JSContext* cx, uint32_t nbytes); -/* +/** * Create a new ArrayBuffer with the given byte length. */ extern JS_FRIEND_API(JSObject*) JS_NewArrayBuffer(JSContext* cx, uint32_t nbytes); -/* +/** * Check whether obj supports JS_GetTypedArray* APIs. Note that this may return * false if a security wrapper is encountered that denies the unwrapping. If * this test or one of the JS_Is*Array tests succeeds, then it is safe to call @@ -1708,13 +1716,13 @@ JS_NewArrayBuffer(JSContext* cx, uint32_t nbytes); extern JS_FRIEND_API(bool) JS_IsTypedArrayObject(JSObject* obj); -/* +/** * Ditto for JS_GetSharedTypedArray* APIs. */ extern JS_FRIEND_API(bool) JS_IsSharedTypedArrayObject(JSObject* obj); -/* +/** * Check whether obj supports JS_GetArrayBufferView* APIs. Note that this may * return false if a security wrapper is encountered that denies the * unwrapping. If this test or one of the more specific tests succeeds, then it @@ -1958,7 +1966,7 @@ JS_IsArrayBufferObject(JSObject* obj); extern JS_FRIEND_API(bool) JS_IsSharedArrayBufferObject(JSObject* obj); -/* +/** * Return the available byte length of an array buffer. * * |obj| must have passed a JS_IsArrayBufferObject test, or somehow be known @@ -1968,7 +1976,7 @@ JS_IsSharedArrayBufferObject(JSObject* obj); extern JS_FRIEND_API(uint32_t) JS_GetArrayBufferByteLength(JSObject* obj); -/* +/** * Return true if the arrayBuffer contains any data. This will return false for * ArrayBuffer.prototype and neutered ArrayBuffers. * @@ -1979,7 +1987,7 @@ JS_GetArrayBufferByteLength(JSObject* obj); extern JS_FRIEND_API(bool) JS_ArrayBufferHasData(JSObject* obj); -/* +/** * Check whether the obj is ArrayBufferObject and memory mapped. Note that this * may return false if a security wrapper is encountered that denies the * unwrapping. @@ -1987,7 +1995,7 @@ JS_ArrayBufferHasData(JSObject* obj); extern JS_FRIEND_API(bool) JS_IsMappedArrayBufferObject(JSObject* obj); -/* +/** * Return the number of elements in a typed array. * * |obj| must have passed a JS_IsTypedArrayObject/JS_Is*Array test, or somehow @@ -1997,7 +2005,7 @@ JS_IsMappedArrayBufferObject(JSObject* obj); extern JS_FRIEND_API(uint32_t) JS_GetTypedArrayLength(JSObject* obj); -/* +/** * Return the byte offset from the start of an array buffer to the start of a * typed array view. * @@ -2008,7 +2016,7 @@ JS_GetTypedArrayLength(JSObject* obj); extern JS_FRIEND_API(uint32_t) JS_GetTypedArrayByteOffset(JSObject* obj); -/* +/** * Return the byte length of a typed array. * * |obj| must have passed a JS_IsTypedArrayObject/JS_Is*Array test, or somehow @@ -2018,7 +2026,7 @@ JS_GetTypedArrayByteOffset(JSObject* obj); extern JS_FRIEND_API(uint32_t) JS_GetTypedArrayByteLength(JSObject* obj); -/* +/** * Check whether obj supports JS_ArrayBufferView* APIs. Note that this may * return false if a security wrapper is encountered that denies the * unwrapping. @@ -2026,7 +2034,7 @@ JS_GetTypedArrayByteLength(JSObject* obj); extern JS_FRIEND_API(bool) JS_IsArrayBufferViewObject(JSObject* obj); -/* +/** * More generic name for JS_GetTypedArrayByteLength to cover DataViews as well */ extern JS_FRIEND_API(uint32_t) @@ -2086,14 +2094,14 @@ JS_GetSharedFloat32ArrayData(JSObject* obj, const JS::AutoCheckCannotGC&); extern JS_FRIEND_API(double*) JS_GetSharedFloat64ArrayData(JSObject* obj, const JS::AutoCheckCannotGC&); -/* +/** * Same as above, but for any kind of ArrayBufferView. Prefer the type-specific * versions when possible. */ extern JS_FRIEND_API(void*) JS_GetArrayBufferViewData(JSObject* obj, const JS::AutoCheckCannotGC&); -/* +/** * Return the ArrayBuffer underlying an ArrayBufferView. If the buffer has been * neutered, this will still return the neutered buffer. |obj| must be an * object that would return true for JS_IsArrayBufferViewObject(). @@ -2106,7 +2114,7 @@ typedef enum { KeepData } NeuterDataDisposition; -/* +/** * Set an ArrayBuffer's length to 0 and neuter all of its views. * * The |changeData| argument is a hint to inform internal behavior with respect @@ -2119,7 +2127,7 @@ extern JS_FRIEND_API(bool) JS_NeuterArrayBuffer(JSContext* cx, JS::HandleObject obj, NeuterDataDisposition changeData); -/* +/** * Check whether the obj is ArrayBufferObject and neutered. Note that this * may return false if a security wrapper is encountered that denies the * unwrapping. @@ -2127,13 +2135,13 @@ JS_NeuterArrayBuffer(JSContext* cx, JS::HandleObject obj, extern JS_FRIEND_API(bool) JS_IsNeuteredArrayBufferObject(JSObject* obj); -/* +/** * Check whether obj supports JS_GetDataView* APIs. */ JS_FRIEND_API(bool) JS_IsDataViewObject(JSObject* obj); -/* +/** * Create a new DataView using the given ArrayBuffer for storage. The given * buffer must be an ArrayBuffer (or a cross-compartment wrapper of an * ArrayBuffer), and the offset and length must fit within the bounds of the @@ -2143,7 +2151,7 @@ JS_IsDataViewObject(JSObject* obj); JS_FRIEND_API(JSObject*) JS_NewDataView(JSContext* cx, JS::HandleObject arrayBuffer, uint32_t byteOffset, int32_t byteLength); -/* +/** * Return the byte offset of a data view into its array buffer. |obj| must be a * DataView. * @@ -2154,7 +2162,7 @@ JS_NewDataView(JSContext* cx, JS::HandleObject arrayBuffer, uint32_t byteOffset, JS_FRIEND_API(uint32_t) JS_GetDataViewByteOffset(JSObject* obj); -/* +/** * Return the byte length of a data view. * * |obj| must have passed a JS_IsDataViewObject test, or somehow be known that @@ -2165,7 +2173,7 @@ JS_GetDataViewByteOffset(JSObject* obj); JS_FRIEND_API(uint32_t) JS_GetDataViewByteLength(JSObject* obj); -/* +/** * Return a pointer to the beginning of the data referenced by a DataView. * * |obj| must have passed a JS_IsDataViewObject test, or somehow be known that @@ -2178,7 +2186,7 @@ JS_GetDataViewData(JSObject* obj, const JS::AutoCheckCannotGC&); namespace js { -/* +/** * Add a watchpoint -- in the Object.prototype.watch sense -- to |obj| for the * property |id|, using the callable object |callable| as the function to be * called for notifications. @@ -2190,7 +2198,7 @@ namespace js { extern JS_FRIEND_API(bool) WatchGuts(JSContext* cx, JS::HandleObject obj, JS::HandleId id, JS::HandleObject callable); -/* +/** * Remove a watchpoint -- in the Object.prototype.watch sense -- from |obj| for * the property |id|. * @@ -2209,7 +2217,7 @@ enum class InlinableNative : uint16_t; } // namespace js -/* +/** * A class, expected to be passed by value, which represents the CallArgs for a * JSJitGetterOp. */ @@ -2229,7 +2237,7 @@ class JSJitGetterCallArgs : protected JS::MutableHandleValue } }; -/* +/** * A class, expected to be passed by value, which represents the CallArgs for a * JSJitSetterOp. */ @@ -2252,7 +2260,7 @@ class JSJitSetterCallArgs : protected JS::MutableHandleValue struct JSJitMethodCallArgsTraits; -/* +/** * A class, expected to be passed by reference, which represents the CallArgs * for a JSJitMethodOp. */ @@ -2299,11 +2307,6 @@ struct JSJitMethodCallArgsTraits static const size_t offsetOfArgc = offsetof(JSJitMethodCallArgs, argc_); }; -/* - * This struct contains metadata passed from the DOM to the JS Engine for JIT - * optimizations on DOM property accessors. Eventually, this should be made - * available to general JSAPI users, but we are not currently ready to do so. - */ typedef bool (* JSJitGetterOp)(JSContext* cx, JS::HandleObject thisObj, void* specializedThis, JSJitGetterCallArgs args); @@ -2314,6 +2317,11 @@ typedef bool (* JSJitMethodOp)(JSContext* cx, JS::HandleObject thisObj, void* specializedThis, const JSJitMethodCallArgs& args); +/** + * This struct contains metadata passed from the DOM to the JS Engine for JIT + * optimizations on DOM property accessors. Eventually, this should be made + * available to general JSAPI users, but we are not currently ready to do so. + */ struct JSJitInfo { enum OpType { Getter, @@ -2353,24 +2361,31 @@ struct JSJitInfo { static_assert(Any & Object, "Any must include Object."); static_assert(Any & Null, "Any must include Null."); + /** + * An enum that describes what this getter/setter/method aliases. This + * determines what things can be hoisted past this call, and if this + * call is movable what it can be hoisted past. + */ enum AliasSet { - // An enum that describes what this getter/setter/method aliases. This - // determines what things can be hoisted past this call, and if this - // call is movable what it can be hoisted past. - - // Alias nothing: a constant value, getting it can't affect any other - // values, nothing can affect it. + /** + * Alias nothing: a constant value, getting it can't affect any other + * values, nothing can affect it. + */ AliasNone, - // Alias things that can modify the DOM but nothing else. Doing the - // call can't affect the behavior of any other function. + /** + * Alias things that can modify the DOM but nothing else. Doing the + * call can't affect the behavior of any other function. + */ AliasDOMSets, - // Alias the world. Calling this can change arbitrary values anywhere - // in the system. Most things fall in this bucket. + /** + * Alias the world. Calling this can change arbitrary values anywhere + * in the system. Most things fall in this bucket. + */ AliasEverything, - // Must be last. + /** Must be last. */ AliasSetCount }; @@ -2403,7 +2418,7 @@ struct JSJitInfo { JSJitGetterOp getter; JSJitSetterOp setter; JSJitMethodOp method; - /* A DOM static method, used for Promise wrappers */ + /** A DOM static method, used for Promise wrappers */ JSNative staticMethod; }; @@ -2423,16 +2438,18 @@ struct JSJitInfo { #define JITINFO_RETURN_TYPE_BITS 8 #define JITINFO_SLOT_INDEX_BITS 10 - // The OpType that says what sort of function we are. + /** The OpType that says what sort of function we are. */ uint32_t type_ : JITINFO_OP_TYPE_BITS; - // The alias set for this op. This is a _minimal_ alias set; in - // particular for a method it does not include whatever argument - // conversions might do. That's covered by argTypes and runtime - // analysis of the actual argument types being passed in. + /** + * The alias set for this op. This is a _minimal_ alias set; in + * particular for a method it does not include whatever argument + * conversions might do. That's covered by argTypes and runtime + * analysis of the actual argument types being passed in. + */ uint32_t aliasSet_ : JITINFO_ALIAS_SET_BITS; - // The return type tag. Might be JSVAL_TYPE_UNKNOWN. + /** The return type tag. Might be JSVAL_TYPE_UNKNOWN. */ uint32_t returnType_ : JITINFO_RETURN_TYPE_BITS; static_assert(OpTypeCount <= (1 << JITINFO_OP_TYPE_BITS), @@ -2446,29 +2463,46 @@ struct JSJitInfo { #undef JITINFO_ALIAS_SET_BITS #undef JITINFO_OP_TYPE_BITS - uint32_t isInfallible : 1; /* Is op fallible? False in setters. */ - uint32_t isMovable : 1; /* Is op movable? To be movable the op must - not AliasEverything, but even that might - not be enough (e.g. in cases when it can - throw or is explicitly not movable). */ - uint32_t isEliminatable : 1; /* Can op be dead-code eliminated? Again, this - depends on whether the op can throw, in - addition to the alias set. */ + /** Is op fallible? False in setters. */ + uint32_t isInfallible : 1; + + /** + * Is op movable? To be movable the op must + * not AliasEverything, but even that might + * not be enough (e.g. in cases when it can + * throw or is explicitly not movable). + */ + uint32_t isMovable : 1; + + /** + * Can op be dead-code eliminated? Again, this + * depends on whether the op can throw, in + * addition to the alias set. + */ + uint32_t isEliminatable : 1; + // XXXbz should we have a JSValueType for the type of the member? - uint32_t isAlwaysInSlot : 1; /* True if this is a getter that can always - get the value from a slot of the "this" - object. */ - uint32_t isLazilyCachedInSlot : 1; /* True if this is a getter that can - sometimes (if the slot doesn't contain - UndefinedValue()) get the value from a - slot of the "this" object. */ - uint32_t isTypedMethod : 1; /* True if this is an instance of - JSTypedMethodJitInfo. */ - uint32_t slotIndex : JITINFO_SLOT_INDEX_BITS; /* If isAlwaysInSlot or - isSometimesInSlot is true, - the index of the slot to - get the value from. - Otherwise 0. */ + /** + * True if this is a getter that can always + * get the value from a slot of the "this" object. + */ + uint32_t isAlwaysInSlot : 1; + + /** + * True if this is a getter that can sometimes (if the slot doesn't contain + * UndefinedValue()) get the value from a slot of the "this" object. + */ + uint32_t isLazilyCachedInSlot : 1; + + /** True if this is an instance of JSTypedMethodJitInfo. */ + uint32_t isTypedMethod : 1; + + /** + * If isAlwaysInSlot or isSometimesInSlot is true, + * the index of the slot to get the value from. + * Otherwise 0. + */ + uint32_t slotIndex : JITINFO_SLOT_INDEX_BITS; static const size_t maxSlotIndex = (1 << JITINFO_SLOT_INDEX_BITS) - 1; @@ -2563,7 +2597,7 @@ bool IdMatchesAtom(jsid id, JSAtom* atom); } // namespace detail } // namespace js -/* +/** * Must not be used on atoms that are representable as integer jsids. * Prefer NameToId or AtomToId over this function: * @@ -2629,7 +2663,7 @@ IdToValue(jsid id) return JS::UndefinedValue(); } -/* +/** * If the embedder has registered a ScriptEnvironmentPreparer, * PrepareScriptEnvironmentAndInvoke will call the preparer's 'invoke' method * with the given |closure|, with the assumption that the preparer will set up @@ -2657,7 +2691,7 @@ JS_FRIEND_API(void) SetScriptEnvironmentPreparer(JSRuntime* rt, ScriptEnvironmentPreparer* preparer); -/* +/** * To help embedders enforce their invariants, we allow them to specify in * advance which JSContext should be passed to JSAPI calls. If this is set * to a non-null value, the assertSameCompartment machinery does double- @@ -2681,7 +2715,7 @@ enum CTypesActivityType { typedef void (* CTypesActivityCallback)(JSContext* cx, CTypesActivityType type); -/* +/** * Sets a callback that is run whenever js-ctypes is about to be used when * calling into C. */ @@ -2713,7 +2747,7 @@ class MOZ_RAII JS_FRIEND_API(AutoCTypesActivityCallback) { typedef JSObject* (* ObjectMetadataCallback)(JSContext* cx, JSObject* obj); -/* +/** * Specify a callback to invoke when creating each JS object in the current * compartment, which may return a metadata object to associate with the * object. @@ -2721,7 +2755,7 @@ typedef JSObject* JS_FRIEND_API(void) SetObjectMetadataCallback(JSContext* cx, ObjectMetadataCallback callback); -/* Get the metadata associated with an object. */ +/** Get the metadata associated with an object. */ JS_FRIEND_API(JSObject*) GetObjectMetadata(JSObject* obj); @@ -2732,7 +2766,7 @@ GetElementsWithAdder(JSContext* cx, JS::HandleObject obj, JS::HandleObject recei JS_FRIEND_API(bool) ForwardToNative(JSContext* cx, JSNative native, const JS::CallArgs& args); -/* +/** * Helper function for HTMLDocument and HTMLFormElement. * * These are the only two interfaces that have [OverrideBuiltins], a named @@ -2773,28 +2807,30 @@ typedef long (*JitExceptionHandler)(void* exceptionRecord, // PEXECTION_RECORD void* context); // PCONTEXT -// Windows uses "structured exception handling" to handle faults. When a fault -// occurs, the stack is searched for a handler (similar to C++ exception -// handling). If the search does not find a handler, the "unhandled exception -// filter" is called. Breakpad uses the unhandled exception filter to do crash -// reporting. Unfortunately, on Win64, JIT code on the stack completely throws -// off this unwinding process and prevents the unhandled exception filter from -// being called. The reason is that Win64 requires unwind information be -// registered for all code regions and JIT code has none. While it is possible -// to register full unwind information for JIT code, this is a lot of work (one -// has to be able to recover the frame pointer at any PC) so instead we register -// a handler for all JIT code that simply calls breakpad's unhandled exception -// filter (which will perform crash reporting and then terminate the process). -// This would be wrong if there was an outer __try block that expected to handle -// the fault, but this is not generally allowed. -// -// Gecko must call SetJitExceptionFilter before any JIT code is compiled and -// only once per process. +/** + * Windows uses "structured exception handling" to handle faults. When a fault + * occurs, the stack is searched for a handler (similar to C++ exception + * handling). If the search does not find a handler, the "unhandled exception + * filter" is called. Breakpad uses the unhandled exception filter to do crash + * reporting. Unfortunately, on Win64, JIT code on the stack completely throws + * off this unwinding process and prevents the unhandled exception filter from + * being called. The reason is that Win64 requires unwind information be + * registered for all code regions and JIT code has none. While it is possible + * to register full unwind information for JIT code, this is a lot of work (one + * has to be able to recover the frame pointer at any PC) so instead we register + * a handler for all JIT code that simply calls breakpad's unhandled exception + * filter (which will perform crash reporting and then terminate the process). + * This would be wrong if there was an outer __try block that expected to handle + * the fault, but this is not generally allowed. + * + * Gecko must call SetJitExceptionFilter before any JIT code is compiled and + * only once per process. + */ extern JS_FRIEND_API(void) SetJitExceptionHandler(JitExceptionHandler handler); #endif -/* +/** * Get the nearest enclosing with scope object for a given function. If the * function is not scripted or is not enclosed by a with scope, returns the * global. @@ -2802,7 +2838,7 @@ SetJitExceptionHandler(JitExceptionHandler handler); extern JS_FRIEND_API(JSObject*) GetNearestEnclosingWithScopeObjectForFunction(JSFunction* fun); -/* +/** * Get the first SavedFrame object in this SavedFrame stack whose principals are * subsumed by the cx's principals. If there is no such frame, return nullptr. * @@ -2831,7 +2867,7 @@ JS_StoreStringPostBarrierCallback(JSContext* cx, void (*callback)(JSTracer* trc, JSString* key, void* data), JSString* key, void* data); -/* +/** * Forcibly clear postbarrier callbacks queued by the previous two methods. * This should be used when the object owning the postbarriered pointers is * being destroyed outside of a garbage collection.