feat(doc): Document all public APIs (#971)

Author: aapoalas

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);