From 2cb14832c81f91e39d0015f237b6bfb652a97285 Mon Sep 17 00:00:00 2001
From: Haled Odat <8566042+HalidOdat@users.noreply.github.com>
Date: Tue, 10 Oct 2023 01:54:36 +0200
Subject: [PATCH] Add some documentation

---
 boa_engine/src/object/internal_methods/mod.rs | 19 +++++++++++++++++--
 boa_engine/src/object/operations.rs           |  1 -
 boa_engine/src/vm/mod.rs                      |  5 ++++-
 3 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/boa_engine/src/object/internal_methods/mod.rs b/boa_engine/src/object/internal_methods/mod.rs
index 0f4685a1e10..e4590d2e743 100644
--- a/boa_engine/src/object/internal_methods/mod.rs
+++ b/boa_engine/src/object/internal_methods/mod.rs
@@ -211,7 +211,9 @@ impl JsObject {
 
     /// Internal method `[[Call]]`
     ///
-    /// Call this object if it has a `[[Call]]` internal method.
+    /// The caller must ensure that the following values are pushed on the stack.
+    ///
+    /// Stack: `this, function, arg0, arg1, ..., argN`
     ///
     /// More information:
     ///  - [ECMAScript reference][spec]
@@ -227,7 +229,9 @@ impl JsObject {
 
     /// Internal method `[[Construct]]`
     ///
-    /// Construct a new instance of this object if this object has a `[[Construct]]` internal method.
+    /// The caller must ensure that the following values are pushed on the stack.
+    ///
+    /// Stack: `function, arg0, arg1, ..., argN, new.target`
     ///
     /// More information:
     ///  - [ECMAScript reference][spec]
@@ -299,17 +303,28 @@ pub(crate) struct InternalObjectMethods {
         fn(&JsObject, argument_count: usize, &mut Context<'_>) -> JsResult<CallValue>,
 }
 
+/// The return value of an internal method (`[[Call]]` or `[[Construct]]`).
+///
+/// This is done to avoid recusion.
 pub(crate) enum CallValue {
+    /// Calling is ready, the frames have been setup.
+    ///
+    /// Requires calling [`Context::run()`].
     Ready,
+
+    /// Further processing is needed.
     Pending {
         func: fn(&JsObject, argument_count: usize, &mut Context<'_>) -> JsResult<CallValue>,
         object: JsObject,
         argument_count: usize,
     },
+
+    /// The value has been computed and is the first element on the stack.
     Complete,
 }
 
 impl CallValue {
+    /// Resolves the [`CallValue`], and return if the value is complete.
     pub(crate) fn resolve(mut self, context: &mut Context<'_>) -> JsResult<bool> {
         while let Self::Pending {
             func,
diff --git a/boa_engine/src/object/operations.rs b/boa_engine/src/object/operations.rs
index a168b29c024..c4f0c811fcf 100644
--- a/boa_engine/src/object/operations.rs
+++ b/boa_engine/src/object/operations.rs
@@ -319,7 +319,6 @@ impl JsObject {
     ) -> JsResult<JsValue> {
         // SKIP: 1. If argumentsList is not present, set argumentsList to a new empty List.
         // SKIP: 2. If IsCallable(F) is false, throw a TypeError exception.
-
         // NOTE(HalidOdat): For object's that are not callable we implement a special __call__ internal method
         //                  that throws on call.
 
diff --git a/boa_engine/src/vm/mod.rs b/boa_engine/src/vm/mod.rs
index f0baadc656c..e36b3d84584 100644
--- a/boa_engine/src/vm/mod.rs
+++ b/boa_engine/src/vm/mod.rs
@@ -293,7 +293,10 @@ impl Context<'_> {
             | Opcode::CallEvalSpread
             | Opcode::New
             | Opcode::NewSpread
-            | Opcode::Return => {
+            | Opcode::Return
+            | Opcode::SuperCall
+            | Opcode::SuperCallSpread
+            | Opcode::SuperCallDerived => {
                 println!();
             }
             _ => {}