From e1b2abbc86dd32cc6805f6a1b89c8e6cc42a6c01 Mon Sep 17 00:00:00 2001
From: TheDoctor314 <64731940+TheDoctor314@users.noreply.github.com>
Date: Sun, 5 Dec 2021 17:21:37 +0530
Subject: [PATCH] Document CodeBlock (#1691)

* Begin adding CodeBlock docs
* Add docs for `CodeBlock` methods and fields
Also fix some typos.
* Add more CodeBlock docs
* Use suggestion from code review
---
 boa/src/vm/code_block.rs | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/boa/src/vm/code_block.rs b/boa/src/vm/code_block.rs
index 670b69edfde..9a2c1169cf8 100644
--- a/boa/src/vm/code_block.rs
+++ b/boa/src/vm/code_block.rs
@@ -1,3 +1,7 @@
+//! CodeBlock
+//!
+//! This module is for the CodeBlock which implements a function representation in the VM
+
 use crate::{
     builtins::function::{
         arguments::Arguments, Captures, ClosureFunctionSignature, Function,
@@ -21,7 +25,7 @@ use std::{convert::TryInto, fmt::Write, mem::size_of};
 
 use super::CallFrame;
 
-/// This represents wether a value can be read from [`CodeBlock`] code.
+/// This represents whether a value can be read from [`CodeBlock`] code.
 pub unsafe trait Readable {}
 
 unsafe impl Readable for u8 {}
@@ -35,12 +39,16 @@ unsafe impl Readable for i64 {}
 unsafe impl Readable for f32 {}
 unsafe impl Readable for f64 {}
 
+/// The internal representation of a JavaScript function.
+///
+/// A CodeBlock is generated for each function compiled by the [ByteCompiler](crate::bytecompiler::ByteCompiler).
+/// It stores the bytecode and the other attributes of the function.
 #[derive(Debug, Trace, Finalize)]
 pub struct CodeBlock {
     /// Name of this function
     pub(crate) name: JsString,
 
-    // The length of this function.
+    /// The number of arguments expected.
     pub(crate) length: u32,
 
     /// Is this function in strict mode.
@@ -52,6 +60,7 @@ pub struct CodeBlock {
     /// [[ThisMode]]
     pub(crate) this_mode: ThisMode,
 
+    /// Parameters passed to this function.
     pub(crate) params: Box<[FormalParameter]>,
 
     /// Bytecode
@@ -63,7 +72,7 @@ pub struct CodeBlock {
     /// Variables names
     pub(crate) variables: Vec<JsString>,
 
-    // Functions inside this function
+    /// Functions inside this function
     pub(crate) functions: Vec<Gc<CodeBlock>>,
 
     /// Indicates if the codeblock contains a lexical name `arguments`
@@ -71,6 +80,7 @@ pub struct CodeBlock {
 }
 
 impl CodeBlock {
+    /// Constructs a new `CodeBlock`.
     pub fn new(name: JsString, length: u32, strict: bool, constructor: bool) -> Self {
         Self {
             code: Vec::new(),
@@ -108,6 +118,10 @@ impl CodeBlock {
         unsafe { self.read_unchecked(offset) }
     }
 
+    /// Get the operands after the `Opcode` pointed to by `pc` as a `String`.
+    /// Modifies the `pc` to point to the next instruction.
+    ///
+    /// Returns an empty `String` if no operands are present.
     pub(crate) fn instruction_operands(&self, pc: &mut usize) -> String {
         let opcode: Opcode = self.code[*pc].try_into().unwrap();
         *pc += size_of::<Opcode>();