Unnecessarily fiddle around with doc comments

nova_vm/src/ecmascript/abstract_operations/operations_on_iterator_objects.rs

@@ -14,7 +14,7 @@ use crate::{
     heap::WellKnownSymbolIndexes,
 };
 
-/// [7.4.1 Iterator Records](https://tc39.es/ecma262/#sec-iterator-records)
+/// ### [7.4.1 Iterator Records](https://tc39.es/ecma262/#sec-iterator-records)
 ///
 /// An Iterator Record is a Record value used to encapsulate an Iterator or
 /// AsyncIterator along with the next method.
@@ -25,7 +25,7 @@ pub(crate) struct IteratorRecord {
     done: bool,
 }
 
-/// [7.4.2 GetIteratorFromMethod ( obj, method )](https://tc39.es/ecma262/#sec-getiteratorfrommethod)
+/// ### [7.4.2 GetIteratorFromMethod ( obj, method )](https://tc39.es/ecma262/#sec-getiteratorfrommethod)
 ///
 /// The abstract operation GetIteratorFromMethod takes arguments obj (an
 /// ECMAScript language value) and method (a function object) and returns
@@ -56,7 +56,7 @@ pub(crate) fn get_iterator_from_method(
     })
 }
 
-/// [7.4.3 GetIterator ( obj, kind )](https://tc39.es/ecma262/#sec-getiterator)
+/// ### [7.4.3 GetIterator ( obj, kind )](https://tc39.es/ecma262/#sec-getiterator)
 ///
 /// The abstract operation GetIterator takes arguments obj (an ECMAScript
 /// language value) and kind (sync or async) and returns either a normal
@@ -120,7 +120,7 @@ pub(crate) fn get_iterator(
     get_iterator_from_method(agent, obj, method)
 }
 
-/// [7.4.4 IteratorNext ( iteratorRecord [ , value ] )](https://tc39.es/ecma262/#sec-iteratornext)
+/// ### [7.4.4 IteratorNext ( iteratorRecord [ , value ] )](https://tc39.es/ecma262/#sec-iteratornext)
 ///
 /// The abstract operation IteratorNext takes argument iteratorRecord (an
 /// Iterator Record) and optional argument value (an ECMAScript language value)
@@ -152,7 +152,7 @@ pub(crate) fn iterator_next(
     )))
 }
 
-/// [7.4.5 IteratorComplete ( iterResult )](https://tc39.es/ecma262/#sec-iteratorcomplete)
+/// ### [7.4.5 IteratorComplete ( iterResult )](https://tc39.es/ecma262/#sec-iteratorcomplete)
 ///
 /// The abstract operation IteratorComplete takes argument iterResult (an
 /// Object) and returns either a normal completion containing a Boolean or a
@@ -163,7 +163,7 @@ pub(crate) fn iterator_complete(agent: &mut Agent, iter_result: Object) -> JsRes
     Ok(to_boolean(agent, done))
 }
 
-/// [7.4.6 IteratorValue ( iterResult )](https://tc39.es/ecma262/#sec-iteratorvalue)
+/// ### [7.4.6 IteratorValue ( iterResult )](https://tc39.es/ecma262/#sec-iteratorvalue)
 ///
 /// The abstract operation IteratorValue takes argument iterResult (an
 /// Object) and returns either a normal completion containing an ECMAScript
@@ -177,17 +177,18 @@ pub(crate) fn iterator_value(agent: &mut Agent, iter_result: Object) -> JsResult
     )
 }
 
-/// [7.4.7 IteratorStep ( iteratorRecord )](https://tc39.es/ecma262/#sec-iteratorstep)
+/// ### [7.4.7 IteratorStep ( iteratorRecord )](https://tc39.es/ecma262/#sec-iteratorstep)
 ///
 /// The abstract operation IteratorStep takes argument iteratorRecord (an
 /// Iterator Record) and returns either a normal completion containing either
 /// an Object or false, or a throw completion. It requests the next value from
-/// iteratorRecord.\[\[Iterator\]\] by calling iteratorRecord.\[\[NextMethod\]\]
-/// and returns either false indicating that the iterator has reached its end
-/// or the IteratorResult object if a next value is available.
+/// iteratorRecord.\[\[Iterator\]\] by calling
+/// iteratorRecord.\[\[NextMethod\]\] and returns either false indicating that
+/// the iterator has reached its end or the IteratorResult object if a next
+/// value is available.
 ///
-/// > NOTE: Instead of returning the boolean value false we return an Option where
-/// > the false state is None. That way we can pass the Object as is.
+/// > NOTE: Instead of returning the boolean value false we return an Option
+/// > where the false state is None. That way we can pass the Object as is.
 pub(crate) fn iterator_step(
     agent: &mut Agent,
     iterator_record: &IteratorRecord,
@@ -207,12 +208,13 @@ pub(crate) fn iterator_step(
     Ok(Some(result))
 }
 
-/// [7.4.8 IteratorClose ( iteratorRecord, completion )](https://tc39.es/ecma262/#sec-iteratorclose)
+/// ### [7.4.8 IteratorClose ( iteratorRecord, completion )](https://tc39.es/ecma262/#sec-iteratorclose)
 ///
 /// The abstract operation IteratorClose takes arguments iteratorRecord (an
 /// Iterator Record) and completion (a Completion Record) and returns a
 /// Completion Record. It is used to notify an iterator that it should perform
-/// any actions it would normally perform when it has reached its completed state.
+/// any actions it would normally perform when it has reached its completed
+/// state.
 pub(crate) fn iterator_close(
     _agent: &mut Agent,
     _iterator_record: &IteratorRecord,
@@ -232,9 +234,10 @@ pub(crate) fn iterator_close(
     todo!()
 }
 
-/// [7.4.9 IfAbruptCloseIterator ( value, iteratorRecord )](https://tc39.es/ecma262/#sec-ifabruptcloseiterator)
+/// ### [7.4.9 IfAbruptCloseIterator ( value, iteratorRecord )](https://tc39.es/ecma262/#sec-ifabruptcloseiterator)
 ///
-/// IfAbruptCloseIterator is a shorthand for a sequence of algorithm steps that use an Iterator Record.
+/// IfAbruptCloseIterator is a shorthand for a sequence of algorithm steps that
+/// use an Iterator Record.
 pub(crate) fn if_abrupt_close_iterator(
     _agent: &mut Agent,
     _value: JsResult<Value>,
@@ -246,7 +249,7 @@ pub(crate) fn if_abrupt_close_iterator(
     todo!()
 }
 
-/// [7.4.10 AsyncIteratorClose ( iteratorRecord, completion )](https://tc39.es/ecma262/#sec-asynciteratorclose)
+/// ### [7.4.10 AsyncIteratorClose ( iteratorRecord, completion )](https://tc39.es/ecma262/#sec-asynciteratorclose)
 ///
 /// The abstract operation AsyncIteratorClose takes arguments iteratorRecord
 /// (an Iterator Record) and completion (a Completion Record) and returns a
@@ -273,12 +276,12 @@ pub(crate) fn async_iterator_close(
     todo!()
 }
 
-/// [7.4.11 CreateIterResultObject ( value, done )](https://tc39.es/ecma262/#sec-createiterresultobject)
+/// ### [7.4.11 CreateIterResultObject ( value, done )](https://tc39.es/ecma262/#sec-createiterresultobject)
 ///
 /// The abstract operation CreateIterResultObject takes arguments value (an
 /// ECMAScript language value) and done (a Boolean) and returns an Object that
-/// conforms to the IteratorResult interface. It creates an object that conforms
-/// to the IteratorResult interface.
+/// conforms to the IteratorResult interface. It creates an object that
+/// conforms to the IteratorResult interface.
 pub(crate) fn create_iter_result_object(_agent: &mut Agent, _value: Value, _done: bool) -> Value {
     // 1. Let obj be OrdinaryObjectCreate(%Object.prototype%).
     // 2. Perform ! CreateDataPropertyOrThrow(obj, "value", value).
@@ -287,7 +290,7 @@ pub(crate) fn create_iter_result_object(_agent: &mut Agent, _value: Value, _done
     todo!()
 }
 
-/// [7.4.12 CreateListIteratorRecord ( list )](https://tc39.es/ecma262/#sec-createlistiteratorRecord)
+/// ### [7.4.12 CreateListIteratorRecord ( list )](https://tc39.es/ecma262/#sec-createlistiteratorRecord)
 ///
 /// The abstract operation CreateListIteratorRecord takes argument list (a List
 /// of ECMAScript language values) and returns an Iterator Record. It creates
@@ -303,7 +306,7 @@ pub(crate) fn create_list_iterator_record(_agent: &mut Agent, _list: &[Value]) -
     todo!()
 }
 
-/// [7.4.13 IteratorToList ( iteratorRecord )](https://tc39.es/ecma262/#sec-iteratortolist)
+/// ### [7.4.13 IteratorToList ( iteratorRecord )](https://tc39.es/ecma262/#sec-iteratortolist)
 ///
 /// The abstract operation IteratorToList takes argument iteratorRecord (an
 /// Iterator Record) and returns either a normal completion containing a List

nova_vm/src/ecmascript/abstract_operations/operations_on_objects.rs

@@ -200,6 +200,7 @@ pub(crate) fn get_method(
 }
 
 /// ### [7.3.12 HasProperty ( O, P )](https://tc39.es/ecma262/#sec-hasproperty)
+///
 /// The abstract operation HasProperty takes arguments O (an Object) and P (a
 /// property key) and returns either a normal completion containing a Boolean
 /// or a throw completion. It is used to determine whether an object has a
@@ -270,6 +271,7 @@ pub(crate) fn call_function(
 }
 
 /// ### [7.3.25 GetFunctionRealm ( obj )](https://tc39.es/ecma262/#sec-getfunctionrealm)
+///
 /// The abstract operation GetFunctionRealm takes argument obj (a function
 /// object) and returns either a normal completion containing a Realm Record or
 /// a throw completion.

nova_vm/src/ecmascript/abstract_operations/testing_and_comparison.rs

@@ -156,8 +156,7 @@ pub(crate) fn same_value_zero(
     same_value_non_number(agent, x, y)
 }
 
-/// 7.2.12 SameValueNonNumber ( x, y )
-/// https://tc39.es/ecma262/#sec-samevaluenonnumber
+/// ### [7.2.12 SameValueNonNumber ( x, y )](https://tc39.es/ecma262/#sec-samevaluenonnumber)
 pub(crate) fn same_value_non_number<T: Copy + Into<Value>>(_agent: &mut Agent, x: T, y: T) -> bool {
     let x: Value = x.into();
     let y: Value = y.into();
@@ -193,21 +192,20 @@ pub(crate) fn same_value_non_number<T: Copy + Into<Value>>(_agent: &mut Agent, x
     todo!()
 }
 
-/// [7.2.13 IsLessThan ( x, y, LeftFirst )](https://tc39.es/ecma262/#sec-islessthan)
+/// ### [7.2.13 IsLessThan ( x, y, LeftFirst )](https://tc39.es/ecma262/#sec-islessthan)
 ///
 /// The abstract operation IsLessThan takes arguments x (an ECMAScript language
 /// value), y (an ECMAScript language value), and LeftFirst (a Boolean) and
-/// returns either a normal completion containing either a Boolean or undefined,
-/// or a throw completion. It provides the semantics for the comparison x < y,
-/// returning true, false, or undefined (which indicates that at least one
-/// operand is NaN). The LeftFirst flag is used to control the order in which
-/// operations with potentially visible side-effects are performed upon x and y.
-/// It is necessary because ECMAScript specifies left to right evaluation of
-/// expressions. If LeftFirst is true, the x parameter corresponds to an
-/// expression that occurs to the left of the y parameter's corresponding
-/// expression. If LeftFirst is false, the reverse is the case and operations
-/// must be performed upon y before x. It performs the following steps when
-/// called:
+/// returns either a normal completion containing either a Boolean or
+/// undefined, or a throw completion. It provides the semantics for the
+/// comparison x < y, returning true, false, or undefined (which indicates that
+/// at least one operand is NaN). The LeftFirst flag is used to control the
+/// order in which operations with potentially visible side-effects are
+/// performed upon x and y. It is necessary because ECMAScript specifies left
+/// to right evaluation of expressions. If LeftFirst is true, the x parameter
+/// corresponds to an expression that occurs to the left of the y parameter's
+/// corresponding expression. If LeftFirst is false, the reverse is the case
+/// and operations must be performed upon y before x.
 pub(crate) fn is_less_than<const LEFT_FIRST: bool>(
     agent: &mut Agent,
     x: impl Into<Value> + Copy,
@@ -318,7 +316,7 @@ pub(crate) fn is_less_than<const LEFT_FIRST: bool>(
     }
 }
 
-/// [7.2.14 IsLooselyEqual ( x, y )](https://tc39.es/ecma262/#sec-islooselyequal)
+/// ### [7.2.14 IsLooselyEqual ( x, y )](https://tc39.es/ecma262/#sec-islooselyequal)
 ///
 /// The abstract operation IsLooselyEqual takes arguments x (an ECMAScript
 /// language value) and y (an ECMAScript language value) and returns either a
@@ -424,7 +422,7 @@ pub(crate) fn is_loosely_equal(
     Ok(false)
 }
 
-/// [7.2.14 IsStrictlyEqual ( x, y )](https://tc39.es/ecma262/#sec-isstrictlyequal)
+/// ### [7.2.14 IsStrictlyEqual ( x, y )](https://tc39.es/ecma262/#sec-isstrictlyequal)
 ///
 /// The abstract operation IsStrictlyEqual takes arguments x (an ECMAScript
 /// language value) and y (an ECMAScript language value) and returns a Boolean.

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

@@ -1,8 +1,9 @@
 use crate::heap::{element_array::ElementsVector, indexes::ObjectIndex};
 
-/// An Array is an exotic object that gives special treatment to array index property keys (see 6.1.7).
-/// A property whose property name is an array index is also called an element. Every Array has a
-/// non-configurable "**length**" property whose value is always a non-negative integral Number whose
+/// An Array is an exotic object that gives special treatment to array index
+/// property keys (see 6.1.7). A property whose property name is an array index
+/// is also called an element. Every Array has a non-configurable "**length**"
+/// property whose value is always a non-negative integral Number whose
 /// mathematical value is strictly less than 2**32.
 #[derive(Debug, Clone, Copy)]
 pub struct ArrayHeapData {

nova_vm/src/ecmascript/builtins/array_buffer/abstract_operations.rs

@@ -103,8 +103,8 @@ pub(crate) fn array_buffer_byte_length(
 
 /// ### [25.1.3.3 IsDetachedBuffer ( arrayBuffer )](https://tc39.es/ecma262/#sec-isdetachedbuffer)
 ///
-/// The abstract operation IsDetachedBuffer takes argument *arrayBuffer* (an ArrayBuffer or a
-/// SharedArrayBuffer) and returns a Boolean.
+/// The abstract operation IsDetachedBuffer takes argument *arrayBuffer* (an
+/// ArrayBuffer or a SharedArrayBuffer) and returns a Boolean.
 pub(crate) fn is_detached_buffer(agent: &Agent, array_buffer: ArrayBuffer) -> bool {
     // 1. If arrayBuffer.[[ArrayBufferData]] is null, return true.
     // 2. Return false.
@@ -113,9 +113,9 @@ pub(crate) fn is_detached_buffer(agent: &Agent, array_buffer: ArrayBuffer) -> bo
 
 /// ### [25.1.3.4 DetachArrayBuffer ( arrayBuffer \[ , key \] )](https://tc39.es/ecma262/#sec-detacharraybuffer)
 ///
-/// The abstract operation DetachArrayBuffer takes argument *arrayBuffer* (an ArrayBuffer)
-/// and optional argument *key* (anything) and returns either a normal completion
-/// containing UNUSED or a throw completion.
+/// The abstract operation DetachArrayBuffer takes argument *arrayBuffer* (an
+/// ArrayBuffer) and optional argument *key* (anything) and returns either a
+/// normal completion containing UNUSED or a throw completion.
 pub(crate) fn detach_array_buffer(
     array_buffer: ArrayBuffer,
     agent: &mut Agent,
@@ -140,12 +140,12 @@ pub(crate) fn detach_array_buffer(
 
 /// ### [25.1.3.5 CloneArrayBuffer ( srcBuffer, srcByteOffset, srcLength )](https://tc39.es/ecma262/#sec-clonearraybuffer)
 ///
-/// The abstract operation CloneArrayBuffer takes arguments srcBuffer (an ArrayBuffer
-/// or a SharedArrayBuffer), srcByteOffset (a non-negative integer), and srcLength
-/// (a non-negative integer) and returns either a normal completion containing an
-/// ArrayBuffer or a throw completion. It creates a new ArrayBuffer whose data is a
-/// copy of srcBuffer's data over the range starting at srcByteOffset and continuing
-/// for srcLength bytes.
+/// The abstract operation CloneArrayBuffer takes arguments srcBuffer (an
+/// ArrayBuffer or a SharedArrayBuffer), srcByteOffset (a non-negative
+/// integer), and srcLength (a non-negative integer) and returns either a
+/// normal completion containing an ArrayBuffer or a throw completion. It
+/// creates a new ArrayBuffer whose data is a copy of srcBuffer's data over the
+/// range starting at srcByteOffset and continuing for srcLength bytes.
 pub(crate) fn clone_array_buffer(
     agent: &mut Agent,
     src_buffer: ArrayBuffer,
@@ -193,7 +193,10 @@ pub(crate) fn clone_array_buffer(
 
 /// ### [25.1.3.6 GetArrayBufferMaxByteLengthOption ( options )](https://tc39.es/ecma262/#sec-getarraybuffermaxbytelengthoption)
 ///
-/// The abstract operation GetArrayBufferMaxByteLengthOption takes argument options (an ECMAScript language value) and returns either a normal completion containing either a non-negative integer or EMPTY, or a throw completion.
+/// The abstract operation GetArrayBufferMaxByteLengthOption takes argument
+/// options (an ECMAScript language value) and returns either a normal
+/// completion containing either a non-negative integer or EMPTY, or a throw
+/// completion.
 pub(crate) fn get_array_buffer_max_byte_length_option(
     agent: &mut Agent,
     options: Value,
@@ -233,18 +236,22 @@ pub(crate) fn get_array_buffer_max_byte_length_option(
 
 /// ### [25.1.3.7 HostResizeArrayBuffer ( buffer, newByteLength )](https://tc39.es/ecma262/#sec-hostresizearraybuffer)
 ///
-/// The host-defined abstract operation HostResizeArrayBuffer takes arguments buffer
-/// (an ArrayBuffer) and newByteLength (a non-negative integer) and returns either a
-/// normal completion containing either HANDLED or UNHANDLED, or a throw completion.
-/// It gives the host an opportunity to perform implementation-defined resizing of buffer.
-/// If the host chooses not to handle resizing of buffer,
-/// it may return UNHANDLED for the default behaviour.
+/// The host-defined abstract operation HostResizeArrayBuffer takes arguments
+/// buffer (an ArrayBuffer) and newByteLength (a non-negative integer) and
+/// returns either a normal completion containing either HANDLED or UNHANDLED,
+/// or a throw completion. It gives the host an opportunity to perform
+/// implementation-defined resizing of buffer. If the host chooses not to
+/// handle resizing of buffer, it may return UNHANDLED for the default
+/// behaviour.
 ///
-/// The implementation of HostResizeArrayBuffer must conform to the following requirements:
+/// The implementation of HostResizeArrayBuffer must conform to the following
+/// requirements:
 /// * The abstract operation does not detach buffer.
-/// * If the abstract operation completes normally with HANDLED, buffer.[[ArrayBufferByteLength]] is newByteLength.
+/// * If the abstract operation completes normally with HANDLED,
+/// buffer.[[ArrayBufferByteLength]] is newByteLength.
 ///
-/// The default implementation of HostResizeArrayBuffer is to return NormalCompletion(UNHANDLED).
+/// The default implementation of HostResizeArrayBuffer is to return
+/// NormalCompletion(UNHANDLED).
 pub(crate) fn host_resize_array_buffer(
     buffer: ArrayBuffer,
     agent: &mut Agent,
@@ -471,7 +478,11 @@ pub(crate) fn set_value_in_buffer(
 
 /// ### [25.1.3.18 GetModifySetValueInBuffer ( arrayBuffer, byteIndex, type, value, op )](https://tc39.es/ecma262/#sec-getmodifysetvalueinbuffer)
 ///
-/// The abstract operation GetModifySetValueInBuffer takes arguments arrayBuffer (an ArrayBuffer or a SharedArrayBuffer), byteIndex (a non-negative integer), type (a TypedArray element type), value (a Number or a BigInt), and op (a read-modify-write modification function) and returns a Number or a BigInt.
+/// The abstract operation GetModifySetValueInBuffer takes arguments
+/// arrayBuffer (an ArrayBuffer or a SharedArrayBuffer), byteIndex (a
+/// non-negative integer), type (a TypedArray element type), value (a Number or
+/// a BigInt), and op (a read-modify-write modification function) and returns a
+/// Number or a BigInt.
 pub(crate) fn get_modify_set_value_in_buffer(
     _array_buffer: ArrayBuffer,
     _byte_index: u32,

nova_vm/src/ecmascript/builtins/ordinary.rs

@@ -743,7 +743,7 @@ pub(crate) fn ordinary_own_property_keys(
     Ok(keys)
 }
 
-/// ## [10.1.12 OrdinaryObjectCreate ( proto \[ , additionalInternalSlotsList \] )](https://tc39.es/ecma262/#sec-ordinaryobjectcreate)
+/// ### [10.1.12 OrdinaryObjectCreate ( proto \[ , additionalInternalSlotsList \] )](https://tc39.es/ecma262/#sec-ordinaryobjectcreate)
 ///
 /// The abstract operation OrdinaryObjectCreate takes argument proto (an Object
 /// or null) and optional argument additionalInternalSlotsList (a List of names