feat(doc): Document all public APIs

nova_vm/src/ecmascript.rs

@@ -2,7 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
-//!# [ECMAScript language](https://tc39.es/ecma262/)
+//! # [ECMAScript language](https://tc39.es/ecma262/)
 //!
 //! This module is the main entry point into the Nova JavaScript API and its
 //! implementation of the ECMAScript language specification.

nova_vm/src/ecmascript/abstract_operations/operations_on_objects.rs

@@ -2683,7 +2683,7 @@ pub(crate) fn try_private_set<'gc>(
     }
 }
 
-///### [7.3.33 InitializeInstanceElements ( O, constructor )](https://tc39.es/ecma262/#sec-initializeinstanceelements)
+/// ### [7.3.33 InitializeInstanceElements ( O, constructor )](https://tc39.es/ecma262/#sec-initializeinstanceelements)
 ///
 /// The abstract operation InitializeInstanceElements takes arguments O (an
 /// Object) and constructor (an ECMAScript function object) and returns either

nova_vm/src/ecmascript/builtins/array.rs

@@ -38,6 +38,12 @@ use super::{
 };
 
 /// ### [10.4.2 Array Exotic Objects](https://tc39.es/ecma262/#sec-array-exotic-objects)
+///
+/// ## Support status
+///
+/// `Array` in Nova does not support sparse storage. This means that setting the
+/// `length` property will grow the `Array`'s backing storage to the requested
+/// size or larger.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(transparent)]
 pub struct Array<'a>(BaseIndex<'a, ArrayHeapData<'static>>);

nova_vm/src/ecmascript/builtins/array_buffer.rs

@@ -290,8 +290,10 @@ impl<'a> CreateHeapData<ArrayBufferHeapData<'a>, ArrayBuffer<'a>> for Heap {
 #[derive(Debug, Copy, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)]
 #[repr(u8)]
 pub enum AnyArrayBuffer<'a> {
+    /// ## [25.1 ArrayBuffer Objects](https://tc39.es/ecma262/#sec-arraybuffer-objects)
     ArrayBuffer(ArrayBuffer<'a>) = ARRAY_BUFFER_DISCRIMINANT,
     #[cfg(feature = "shared-array-buffer")]
+    /// ## [25.2 SharedArrayBuffer Objects](https://tc39.es/ecma262/#sec-sharedarraybuffer-objects)
     SharedArrayBuffer(SharedArrayBuffer<'a>) = SHARED_ARRAY_BUFFER_DISCRIMINANT,
 }
 bindable_handle!(AnyArrayBuffer);

nova_vm/src/ecmascript/builtins/builtin_constructor.rs

@@ -24,7 +24,8 @@ use super::ArgumentsList;
 
 /// ### [4.4.36 built-in constructor](https://tc39.es/ecma262/#sec-built-in-constructor)
 ///
-/// A class built-in default constructor created in step 14 of [ClassDefinitionEvaluation].
+/// A class built-in default constructor created in step 14 of
+/// [ClassDefinitionEvaluation].
 ///
 /// #### Examples
 ///
@@ -45,12 +46,6 @@ arena_vec_access!(
     builtin_constructors
 );
 
-impl BuiltinConstructorFunction<'_> {
-    pub const fn is_constructor(self) -> bool {
-        true
-    }
-}
-
 impl<'a> FunctionInternalProperties<'a> for BuiltinConstructorFunction<'a> {
     fn get_name(self, agent: &Agent) -> &String<'a> {
         &self.get(agent).class_name

nova_vm/src/ecmascript/builtins/builtin_function.rs

@@ -387,7 +387,10 @@ pub type ConstructorFn = for<'gc> fn(
 #[allow(unpredictable_function_pointer_comparisons)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Behaviour {
+    /// Regular JavaScript function not callable with the `new` keyword.
     Regular(RegularFn),
+    /// JavaScript function callable with the `new` keyword, and possibly
+    /// without it.
     Constructor(ConstructorFn),
 }
 
@@ -446,27 +449,37 @@ pub(crate) trait BuiltinIntrinsic: Builtin {
 }
 /// Helper trait for defining builtin getter function properties.
 pub trait BuiltinGetter: Builtin {
+    /// Accessor property's getter function's `name` property value.
     const GETTER_NAME: String<'static> = Self::NAME;
+    /// Accessor property's getter function's call behaviour.
     const GETTER_BEHAVIOUR: Behaviour = Self::BEHAVIOUR;
 }
 /// Helper trait for defining builtin setter function properties.
 pub trait BuiltinSetter: Builtin {
+    /// Accessor property's setter function's `name` property value.
     const SETTER_NAME: String<'static> = Self::NAME;
+    /// Accessor property's setter function's call behaviour.
     const SETTER_BEHAVIOUR: Behaviour = Self::BEHAVIOUR;
 }
 
 /// Builtin function creation arguments.
 #[derive(Debug, Default)]
 pub struct BuiltinFunctionArgs<'a> {
+    /// The builtin function's `length` property initial value.
     pub length: u32,
+    /// The builtin function's `name` property initial value.
     pub name: &'static str,
+    /// The builtin function's Realm. Defaults to the current Realm.
     pub realm: Option<Realm<'a>>,
+    /// The builtin function's prototype. Defaults to the current Realm's
+    /// `Function.prototype`
     pub prototype: Option<Object<'a>>,
+    /// An optional prefix for the builtin function's name.
     pub prefix: Option<&'static str>,
 }
 
 impl<'a> BuiltinFunctionArgs<'a> {
-    // Create new builtin function creation arguments with length and name.
+    /// Create new builtin function creation arguments with length and name.
     pub fn new(length: u32, name: &'static str) -> Self {
         Self {
             length,
@@ -475,7 +488,7 @@ impl<'a> BuiltinFunctionArgs<'a> {
         }
     }
 
-    // Create new builtin function creation arguments with length, name, and a realm.
+    /// Create new builtin function creation arguments with length, name, and a realm.
     pub fn new_with_realm(length: u32, name: &'static str, realm: Realm<'a>) -> Self {
         Self {
             length,

nova_vm/src/ecmascript/builtins/control_abstraction_objects/generator_objects.rs

@@ -32,7 +32,7 @@ object_handle!(Generator);
 arena_vec_access!(Generator, 'a, GeneratorHeapData, generators);
 
 impl Generator<'_> {
-    ///### [27.5.3.3 GeneratorResume ( generator, value, generatorBrand )](https://tc39.es/ecma262/#sec-generatorresume)
+    /// ### [27.5.3.3 GeneratorResume ( generator, value, generatorBrand )](https://tc39.es/ecma262/#sec-generatorresume)
     pub(crate) fn resume<'a>(
         self,
         agent: &mut Agent,
@@ -152,7 +152,7 @@ impl Generator<'_> {
         }
     }
 
-    ///### [27.5.3.4 GeneratorResumeAbrupt ( generator, abruptCompletion, generatorBrand )](https://tc39.es/ecma262/#sec-generatorresumeabrupt)
+    /// ### [27.5.3.4 GeneratorResumeAbrupt ( generator, abruptCompletion, generatorBrand )](https://tc39.es/ecma262/#sec-generatorresumeabrupt)
     /// NOTE: This method only accepts throw completions.
     pub(crate) fn resume_throw<'a>(
         self,
@@ -262,7 +262,7 @@ impl Generator<'_> {
         }
     }
 
-    ///### [27.5.3.4 GeneratorResumeAbrupt ( generator, abruptCompletion, generatorBrand )](https://tc39.es/ecma262/#sec-generatorresumeabrupt)
+    /// ### [27.5.3.4 GeneratorResumeAbrupt ( generator, abruptCompletion, generatorBrand )](https://tc39.es/ecma262/#sec-generatorresumeabrupt)
     /// NOTE: This method only accepts return completions.
     pub(crate) fn resume_return<'a>(
         self,

nova_vm/src/ecmascript/builtins/control_abstraction_objects/iteration/iterator_prototype.rs

@@ -81,6 +81,7 @@ impl Builtin for IteratorPrototypeToStringTag {
     const BEHAVIOUR: Behaviour = Behaviour::Regular(IteratorPrototype::get_to_string_tag);
 }
 impl BuiltinGetter for IteratorPrototypeToStringTag {
+    /// Accessor property's getter function's `name` property value.
     const GETTER_NAME: String<'static> = BUILTIN_STRING_MEMORY.get__Symbol_toStringTag_;
 }
 impl BuiltinSetter for IteratorPrototypeToStringTag {

nova_vm/src/ecmascript/builtins/control_abstraction_objects/promise_objects/promise_abstract_operations/promise_capability_records.rs

@@ -40,7 +40,7 @@ pub struct PromiseCapability<'a> {
 }
 
 impl<'a> PromiseCapability<'a> {
-    ///### [27.2.1.5 NewPromiseCapability ( C )](https://tc39.es/ecma262/#sec-newpromisecapability)
+    /// ### [27.2.1.5 NewPromiseCapability ( C )](https://tc39.es/ecma262/#sec-newpromisecapability)
     ///
     /// Create a new PromiseCapability
     ///
@@ -84,7 +84,7 @@ impl<'a> PromiseCapability<'a> {
         }
     }
 
-    ///### [27.2.1.4 FulfillPromise ( promise, value )](https://tc39.es/ecma262/#sec-fulfillpromise)
+    /// ### [27.2.1.4 FulfillPromise ( promise, value )](https://tc39.es/ecma262/#sec-fulfillpromise)
     pub(crate) fn internal_fulfill(&self, agent: &mut Agent, value: Value, gc: NoGcScope) {
         // 1. Assert: The value of promise.[[PromiseState]] is pending.
         // 2. Let reactions be promise.[[PromiseFulfillReactions]].
@@ -108,7 +108,7 @@ impl<'a> PromiseCapability<'a> {
         }
     }
 
-    ///### [27.2.1.7 RejectPromise ( promise, reason )](https://tc39.es/ecma262/#sec-rejectpromise)
+    /// ### [27.2.1.7 RejectPromise ( promise, reason )](https://tc39.es/ecma262/#sec-rejectpromise)
     fn internal_reject(&self, agent: &mut Agent, reason: Value, gc: NoGcScope) {
         // 1. Assert: The value of promise.[[PromiseState]] is pending.
         // 2. Let reactions be promise.[[PromiseRejectReactions]].
@@ -141,7 +141,7 @@ impl<'a> PromiseCapability<'a> {
         }
     }
 
-    ///### [27.2.1.3.2 Promise Resolve Functions](https://tc39.es/ecma262/#sec-promise-resolve-functions)
+    /// ### [27.2.1.3.2 Promise Resolve Functions](https://tc39.es/ecma262/#sec-promise-resolve-functions)
     ///
     /// Resolve the associated [`Promise`] with a given value. Ignored if the
     /// [`Promise`] is already resolved.
@@ -246,7 +246,7 @@ impl<'a> PromiseCapability<'a> {
         // 16. Return undefined.
     }
 
-    ///### [27.2.1.3.2 Promise Resolve Functions](https://tc39.es/ecma262/#sec-promise-resolve-functions)
+    /// ### [27.2.1.3.2 Promise Resolve Functions](https://tc39.es/ecma262/#sec-promise-resolve-functions)
     ///
     /// Try resolve the associated [`Promise`] with a given value. Fails if
     /// resolving would require calling into user-code. Ignored if the
@@ -335,7 +335,7 @@ impl<'a> PromiseCapability<'a> {
         TryResult::Continue(())
     }
 
-    ///### [27.2.1.3.1 Promise Reject Functions](https://tc39.es/ecma262/#sec-promise-reject-functions)
+    /// ### [27.2.1.3.1 Promise Reject Functions](https://tc39.es/ecma262/#sec-promise-reject-functions)
     ///
     /// Reject the associated [`Promise`] with a given value. Ignored if the
     /// [`Promise`] is already resolved.

nova_vm/src/ecmascript/builtins/data_view.rs

@@ -366,8 +366,12 @@ impl HeapSweepWeakReference for SharedDataView<'static> {
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(u8)]
 pub enum AnyDataView<'a> {
+    /// ## [25.3 DataView Objects](https://tc39.es/ecma262/#sec-dataview-objects)
     DataView(DataView<'a>) = DATA_VIEW_DISCRIMINANT,
     #[cfg(feature = "shared-array-buffer")]
+    /// ## [25.3 DataView Objects](https://tc39.es/ecma262/#sec-dataview-objects)
+    ///
+    /// A variant of DataView Objects viewing a SharedArrayBuffer.
     SharedDataView(SharedDataView<'a>) = SHARED_DATA_VIEW_DISCRIMINANT,
 }
 bindable_handle!(AnyDataView);

nova_vm/src/ecmascript/builtins/ecmascript_function.rs

@@ -969,7 +969,6 @@ pub(crate) fn make_constructor<'a>(
         Function::BuiltinConstructorFunction(_)
         | Function::BuiltinPromiseResolvingFunction(_)
         | Function::BuiltinPromiseFinallyFunction(_)
-        | Function::BuiltinPromiseCollectorFunction
         | Function::BuiltinProxyRevokerFunction => unreachable!(),
     }
     // 5. If prototype is not present, then
@@ -1162,7 +1161,6 @@ pub(crate) fn set_function_name<'a>(
         Function::BuiltinConstructorFunction(_)
         | Function::BuiltinPromiseResolvingFunction(_)
         | Function::BuiltinPromiseFinallyFunction(_)
-        | Function::BuiltinPromiseCollectorFunction
         | Function::BuiltinProxyRevokerFunction => unreachable!(),
     }
 }

nova_vm/src/ecmascript/builtins/finalization_registry/data.rs

@@ -79,7 +79,7 @@ impl Default for CleanupRecord<'_> {
         Self {
             cleanup_queue: Default::default(),
             // Note: impossible value currently.
-            callback: Function::BuiltinPromiseCollectorFunction,
+            callback: Function::BuiltinProxyRevokerFunction,
             realm: Realm::_DEF,
             cleanup_requested: false,
         }
@@ -102,7 +102,7 @@ impl<'fr> CleanupRecord<'fr> {
     /// FinalizationRegistry must be previously uninitialised.
     pub(super) unsafe fn initialise(&mut self, realm: Realm, cleanup_callback: Function) {
         debug_assert_eq!(self.realm, Realm::_DEF);
-        debug_assert_eq!(self.callback, Function::BuiltinPromiseCollectorFunction);
+        debug_assert_eq!(self.callback, Function::BuiltinProxyRevokerFunction);
         self.realm = realm.unbind();
         self.callback = cleanup_callback.unbind();
     }

nova_vm/src/ecmascript/builtins/fundamental_objects/function_objects/function_prototype.rs

@@ -416,7 +416,7 @@ impl FunctionPrototype {
                         .unbind(),
                 )
             }
-            Function::BuiltinPromiseCollectorFunction | Function::BuiltinProxyRevokerFunction => {
+            Function::BuiltinProxyRevokerFunction => {
                 unreachable!()
             }
         }

nova_vm/src/ecmascript/builtins/indexed_collections/typed_array_objects/abstract_operations.rs

@@ -485,7 +485,7 @@ pub(crate) trait TypedArrayAbstractOperations<'ta>: Copy + Sized {
         count: usize,
     );
 
-    ///### [23.2.3.26.2 SetTypedArrayFromTypedArray ( target, targetOffset, source )](https://tc39.es/ecma262/#sec-settypedarrayfromtypedarray)
+    /// ### [23.2.3.26.2 SetTypedArrayFromTypedArray ( target, targetOffset, source )](https://tc39.es/ecma262/#sec-settypedarrayfromtypedarray)
     ///
     /// The abstract operation SetTypedArrayFromTypedArray takes arguments
     /// target (a TypedArray), targetOffset (a non-negative integer or +∞), and

nova_vm/src/ecmascript/builtins/managing_memory/finalization_registry_objects/finalization_registry_constructor.rs

@@ -98,7 +98,6 @@ impl FinalizationRegistryConstructor {
             Function::BuiltinPromiseFinallyFunction(_) => {
                 unreachable!("builtin promise finally function constructing FinalizationRegistry")
             }
-            Function::BuiltinPromiseCollectorFunction => todo!(),
             Function::BuiltinProxyRevokerFunction => todo!(),
         };
         // 6. Set finalizationRegistry.[[CleanupCallback]] to

nova_vm/src/ecmascript/builtins/promise.rs

@@ -43,6 +43,10 @@ use crate::{
 /// resolved. An unresolved promise is always in the pending state. A resolved
 /// promise may be pending, fulfilled or rejected.
 ///
+/// ## Support status
+///
+/// `Promise` in Nova does not currently support subclassing.
+///
 /// [Job]: crate::ecmascript::Job
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(transparent)]
@@ -98,7 +102,7 @@ impl<'a> Promise<'a> {
         };
     }
 
-    ///### [27.2.4.7.1 PromiseResolve ( C, x )](https://tc39.es/ecma262/#sec-promise-resolve)
+    /// ### [27.2.4.7.1 PromiseResolve ( C, x )](https://tc39.es/ecma262/#sec-promise-resolve)
     pub(crate) fn resolve(
         agent: &mut Agent,
         x: Value,

nova_vm/src/ecmascript/builtins/reflection/reflect_object.rs

@@ -124,7 +124,7 @@ impl Builtin for ReflectObjectSetPrototypeOf {
 }
 
 impl ReflectObject {
-    ///### [28.1.1 Reflect.apply ( target, thisArgument, argumentsList )](https://tc39.es/ecma262/#sec-reflect.apply)
+    /// ### [28.1.1 Reflect.apply ( target, thisArgument, argumentsList )](https://tc39.es/ecma262/#sec-reflect.apply)
     fn apply<'gc>(
         agent: &mut Agent,
         _this_value: Value,
@@ -214,7 +214,7 @@ impl ReflectObject {
         .map(|o| o.into())
     }
 
-    ///### [28.1.3 Reflect.defineProperty ( target, propertyKey, attributes )](https://tc39.es/ecma262/#sec-reflect.defineproperty)
+    /// ### [28.1.3 Reflect.defineProperty ( target, propertyKey, attributes )](https://tc39.es/ecma262/#sec-reflect.defineproperty)
     fn define_property<'gc>(
         agent: &mut Agent,
         _this_value: Value,
@@ -285,7 +285,7 @@ impl ReflectObject {
         Ok(ret.into())
     }
 
-    ///### [28.1.4 Reflect.deleteProperty ( target, propertyKey )](https://tc39.es/ecma262/#sec-reflect.deleteproperty)
+    /// ### [28.1.4 Reflect.deleteProperty ( target, propertyKey )](https://tc39.es/ecma262/#sec-reflect.deleteproperty)
     fn delete_property<'gc>(
         agent: &mut Agent,
         _this_value: Value,
@@ -373,7 +373,7 @@ impl ReflectObject {
             .internal_get(agent, key.unbind(), receiver.unbind(), gc)
     }
 
-    ///### [28.1.6 Reflect.getOwnPropertyDescriptor ( target, propertyKey )](https://tc39.es/ecma262/#sec-reflect.getownpropertydescriptor)
+    /// ### [28.1.6 Reflect.getOwnPropertyDescriptor ( target, propertyKey )](https://tc39.es/ecma262/#sec-reflect.getownpropertydescriptor)
     fn get_own_property_descriptor<'gc>(
         agent: &mut Agent,
         _this_value: Value,
@@ -418,7 +418,7 @@ impl ReflectObject {
         }
     }
 
-    ///### [28.1.7 Reflect.getPrototypeOf ( target )](https://tc39.es/ecma262/#sec-reflect.getprototypeof)
+    /// ### [28.1.7 Reflect.getPrototypeOf ( target )](https://tc39.es/ecma262/#sec-reflect.getprototypeof)
     fn get_prototype_of<'gc>(
         agent: &mut Agent,
         _this_value: Value,
@@ -444,7 +444,7 @@ impl ReflectObject {
         }
     }
 
-    ///### [28.1.8 Reflect.has ( target, propertyKey )](https://tc39.es/ecma262/#sec-reflect.has)
+    /// ### [28.1.8 Reflect.has ( target, propertyKey )](https://tc39.es/ecma262/#sec-reflect.has)
     fn has<'gc>(
         agent: &mut Agent,
         _this_value: Value,
@@ -483,7 +483,7 @@ impl ReflectObject {
         Ok(ret.into())
     }
 
-    ///### [28.1.9 Reflect.isExtensible ( target )](https://tc39.es/ecma262/#sec-reflect.isextensible)
+    /// ### [28.1.9 Reflect.isExtensible ( target )](https://tc39.es/ecma262/#sec-reflect.isextensible)
     fn is_extensible<'gc>(
         agent: &mut Agent,
         _this_value: Value,
@@ -507,7 +507,7 @@ impl ReflectObject {
         Ok(ret.into())
     }
 
-    ///### [28.1.10 Reflect.ownKeys ( target )](https://tc39.es/ecma262/#sec-reflect.ownkeys)
+    /// ### [28.1.10 Reflect.ownKeys ( target )](https://tc39.es/ecma262/#sec-reflect.ownkeys)
     fn own_keys<'gc>(
         agent: &mut Agent,
         _this_value: Value,
@@ -538,7 +538,7 @@ impl ReflectObject {
         Ok(create_array_from_list(agent, &keys.unbind(), gc.into_nogc()).into())
     }
 
-    ///### [28.1.11 Reflect.preventExtensions ( target )](https://tc39.es/ecma262/#sec-reflect.preventextensions)
+    /// ### [28.1.11 Reflect.preventExtensions ( target )](https://tc39.es/ecma262/#sec-reflect.preventextensions)
     fn prevent_extensions<'gc>(
         agent: &mut Agent,
         _this_value: Value,
@@ -616,7 +616,7 @@ impl ReflectObject {
         Ok(ret.into())
     }
 
-    ///### [28.1.13 Reflect.setPrototypeOf ( target, proto )](https://tc39.es/ecma262/#sec-reflect.setprototypeof)
+    /// ### [28.1.13 Reflect.setPrototypeOf ( target, proto )](https://tc39.es/ecma262/#sec-reflect.setprototypeof)
     fn set_prototype_of<'gc>(
         agent: &mut Agent,
         _this_value: Value,