add docs

Author: Robbepop

crates/wasmi/src/engine/translator/stack2/mod.rs

@@ -8,11 +8,18 @@ use core::num::NonZeroUsize;
 
 #[derive(Debug, Clone)]
 pub struct ValueStack {
+/// The Wasm value stack during translation from Wasm to Wasmi bytecode.
+    /// The stack of operands.
     operands: Vec<StackOperand>,
+    /// All function local constants.
     consts: ConstRegistry,
+    /// All function parameters and locals and their types.
     locals: LocalsRegistry,
+    /// The index of the first [`StackOperand::Local`] on the [`Stack`].
     first_local: Option<OperandIdx>,
+    /// The index of the last [`StackOperand::Local`] on the [`Stack`].
     last_local: Option<OperandIdx>,
+    /// The maximum size of the [`Stack`].
     max_stack_height: usize,
 }
 
@@ -34,41 +41,61 @@ impl From<usize> for OperandIdx {
     }
 }
 
+/// An [`Operand`] on the [`Stack`].
+/// 
+/// This is the internal version of [`Operand`] with information that shall remain
+/// hidden to the outside.
 #[derive(Debug, Copy, Clone)]
 enum StackOperand {
+    /// A local variable.
     Local {
+        /// The index of the local variable.
         index: LocalIdx,
+        /// The previous [`StackOperand::Local`] on the [`Stack`].
         prev_local: Option<OperandIdx>,
+        /// The next [`StackOperand::Local`] on the [`Stack`].
         next_local: Option<OperandIdx>,
     },
+    /// A temporary value on the [`Stack`].
     Temp {
+        /// The type of the temporary value.
         ty: ValType,
     },
+    /// An immediate value on the [`Stack`].
     Immediate {
+        /// The value (and type) of the immediate value.
         val: TypedVal,
     },
 }
 
+/// An operand on the [`Stack`].
 #[derive(Debug, Copy, Clone)]
 pub enum Operand {
+    /// A local variable operand.
     Local(LocalOperand),
+    /// A temporary operand.
     Temp(TempOperand),
+    /// An immediate value operand.
     Immediate(ImmediateOperand),
 }
 
 impl Operand {
+    /// Returns `true` if `self` is an [`Operand::Local`].
     pub fn is_local(self) -> bool {
         matches!(self, Self::Local(_))
     }
 
+    /// Returns `true` if `self` is an [`Operand::Temp`].
     pub fn is_temp(self) -> bool {
         matches!(self, Self::Temp(_))
     }
 
+    /// Returns `true` if `self` is an [`Operand::Immediate`].
     pub fn is_immediate(self) -> bool {
         matches!(self, Self::Immediate(_))
     }
 
+    /// Returns the type of the [`Operand`].
     pub fn ty(self) -> ValType {
         match self {
             Self::Local(local_operand) => local_operand.ty(),
@@ -78,47 +105,60 @@ impl Operand {
     }
 }
 
+/// A local variable on the [`Stack`].
 #[derive(Debug, Copy, Clone)]
 pub struct LocalOperand {
+    /// The index of the local variable.
     index: LocalIdx,
+    /// The type of the local variable.
     ty: ValType,
 }
 
 impl LocalOperand {
+    /// Returns the index of the local variable.
     pub fn index(self) -> LocalIdx {
         self.index
     }
 
+    /// Returns the type of the local variable.
     pub fn ty(self) -> ValType {
         self.ty
     }
 }
 
+/// A temporary on the [`Stack`].
 #[derive(Debug, Copy, Clone)]
 pub struct TempOperand {
+    /// The type of the temporary.
     ty: ValType,
 }
 
 impl TempOperand {
+    /// Returns the type of the temporary.
     pub fn ty(self) -> ValType {
         self.ty
     }
 }
 
+/// An immediate value on the [`Stack`].
 #[derive(Debug, Copy, Clone)]
 pub struct ImmediateOperand {
+    /// The value and type of the immediate value.
     val: TypedVal,
 }
 
 impl ImmediateOperand {
+    /// Returns the value (and type) of the immediate value.
     pub fn val(self) -> TypedVal {
         self.val
     }
 
+    /// Returns the type of the immediate value.
     pub fn ty(self) -> ValType {
         self.val.ty()
     }
 }
 
+/// A local variable index.
 #[derive(Debug, Copy, Clone)]
 pub struct LocalIdx(usize);