Document CodeBlock

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::{
         Captures, ClosureFunctionSignature, Function, NativeFunctionSignature, ThisMode,
@@ -20,7 +24,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 {}
@@ -34,12 +38,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.
@@ -51,6 +59,7 @@ pub struct CodeBlock {
     /// [[ThisMode]]
     pub(crate) this_mode: ThisMode,
 
+    /// Parameters passed to this function.
     pub(crate) params: Box<[FormalParameter]>,
 
     /// Bytecode
@@ -62,11 +71,12 @@ pub struct CodeBlock {
     /// Variables names
     pub(crate) variables: Vec<JsString>,
 
-    // Functions inside this function
+    /// Functions inside this function
     pub(crate) functions: Vec<Gc<CodeBlock>>,
 }
 
 impl CodeBlock {
+    /// Constructs a new `CodeBlock`.
     pub fn new(name: JsString, length: u32, strict: bool, constructor: bool) -> Self {
         Self {
             code: Vec::new(),
@@ -103,6 +113,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>();