refactor: 重构 CallCommand 类并优化文档注释

- 重新组织类文档,增加对 CallCommand 功能和行为的详细描述
- 添加 execute 方法的详细注释,明确参数和返回值的用途
- 优化代码结构,提高可读性和可维护性
This commit is contained in:
Luke 2025-07-21 17:16:54 +08:00
parent b4c933e3d4
commit e7c7451004

View File

@ -5,12 +5,48 @@ import org.jcnc.snow.vm.interfaces.Command;
import org.jcnc.snow.vm.module.*;
/**
* CALL addr nArgs pushes a new stack-frame, transfers the specified
* argument count from the operand stack into the callees local slots
* 0n-1 (left-to-right), then jumps to {@code addr}.
* The CallCommand class implements the {@link Command} interface and represents a subroutine/function call
* instruction in the virtual machine.
* <p>
* This command facilitates method invocation by creating a new stack frame, transferring arguments
* from the operand stack to the callee's local variable store, and jumping to the specified target address.
* </p>
*
* <p>Specific behavior:</p>
* <ul>
* <li>Parses the target address and the number of arguments from the instruction parameters.</li>
* <li>Validates the operands and checks for correct argument count.</li>
* <li>Builds a new local variable store for the callee and transfers arguments from the operand stack
* (left-to-right order, where the top of the stack is the last argument).</li>
* <li>Pushes a new stack frame onto the call stack, saving the return address and local variables.</li>
* <li>Jumps to the specified target address to begin execution of the callee function.</li>
* <li>If any error occurs (e.g., malformed operands, stack underflow), an exception is thrown.</li>
* </ul>
*/
public class CallCommand implements Command {
/**
* Executes the CALL instruction, initiating a subroutine/function call within the virtual machine.
* <p>
* This method handles the creation of a new stack frame for the callee, argument passing,
* and control transfer to the target function address.
* </p>
*
* @param parts The instruction parameters. Must include:
* <ul>
* <li>{@code parts[0]}: The "CALL" operator.</li>
* <li>{@code parts[1]}: The target address of the callee function.</li>
* <li>{@code parts[2]}: The number of arguments to pass.</li>
* </ul>
* @param currentPC The current program counter, used to record the return address for after the call.
* @param operandStack The operand stack manager. Arguments are popped from this stack.
* @param callerLVS The local variable store of the caller function (not directly modified here).
* @param callStack The virtual machine's call stack manager, used to push the new stack frame.
* @return The new program counter value, which is the address of the callee function (i.e., jump target).
* The VM should transfer control to this address after setting up the call frame.
* @throws IllegalArgumentException If the instruction parameters are malformed or missing.
* @throws IllegalStateException If the operand stack does not contain enough arguments.
*/
@Override
public int execute(String[] parts,
int currentPC,