Add OperandStack documentation

Author: chfast

lib/fizzy/stack.hpp

@@ -50,6 +50,11 @@ class Stack
     }
 };
 
+
+/// Contains current frame's locals (including arguments) and operand stack.
+/// The storage space for locals and operand stack together is allocated as a
+/// continuous memory. Elements occupy the storage space in the order:
+/// arguments, local variables, operand stack.
 class OperandStack
 {
     /// The size of the pre-allocated internal storage: 128 bytes.
@@ -75,13 +80,19 @@ class OperandStack
 public:
     /// Default constructor.
     ///
-    /// Based on @p max_stack_height decides if to use small pre-allocated storage or allocate
-    /// large storage.
-    /// Sets the top item pointer to below the stack bottom.
-    OperandStack(span<const Value> args, size_t num_locals, size_t max_stack_height)
+    /// Based on required storage space decides if to use small pre-allocated
+    /// storage or allocate large storage.
+    /// Sets the top stack operand pointer to below the operand stack bottom.
+    /// @param args                 Function arguments. Values are copied at the beginning of the
+    /// storage space.
+    /// @param num_local_variables  The number of the function local variables (excluding
+    ///                             arguments). This number of values is zeroed in the storage space
+    ///                             after the arguments.
+    /// @param max_stack_height     The maximum operand stack height in the function.
+    OperandStack(span<const Value> args, size_t num_local_variables, size_t max_stack_height)
     {
         const auto num_args = args.size();
-        const auto storage_size_required = num_args + num_locals + max_stack_height;
+        const auto storage_size_required = num_args + num_local_variables + max_stack_height;
 
         Value* storage;
         if (storage_size_required <= small_storage_size)
@@ -95,11 +106,11 @@ class OperandStack
         }
 
         m_locals = storage;
-        m_bottom = m_locals + num_args + num_locals;
+        m_bottom = m_locals + num_args + num_local_variables;
         m_top = m_bottom - 1;
 
         std::copy(std::begin(args), std::end(args), m_locals);
-        std::fill_n(m_locals + num_args, num_locals, 0);
+        std::fill_n(m_locals + num_args, num_local_variables, 0);
     }
 
     OperandStack(const OperandStack&) = delete;