Improve documentation for EVM tracing
@@ -675,13 +675,13 @@ enum evmc_revision
/**
- * Generates and executes machine code for given EVM bytecode.
+ * Executes the given EVM bytecode using the input in the message
*
- * All the fun is here. This function actually does something useful.
+ * This function MAY be invoked multiple times for a single EVM instance.
*
- * @param instance A EVM instance.
- * @param context The pointer to the Host execution context to be passed
- * to callback functions. @see ::evmc_context.
+ * @param instance The EVM instance.
+ * @param context The pointer to the Client execution context to be passed
+ * to the callback functions. @see ::evmc_context.
* @param rev Requested EVM specification revision.
* @param msg Call parameters. @see ::evmc_message.
* @param code Reference to the bytecode to be executed.
@@ -703,22 +703,24 @@ struct evmc_tracer_context;
* The callback to trace instructions execution in an EVM.
*
* This function informs the Client what instruction has been executed in the EVM implementation
- * and what are the results of the execution this particular instruction.
+ * and what are the results of executing this particular instruction.
* The message level information (like call depth, destination address, etc.) are not provided here.
* This piece of information can be acquired by inspecting messages being sent to the EVM in
* ::evmc_execute_fn and the results of the messages execution.
*
* @param context The pointer to the Client-side tracing context. This allows to
* implement the tracer in OOP manner.
- * @param step The instruction counter for the current message.
- * @param code_offset The instruction possition in the code.
+ * @param step The instruction counter: number of instructions executed.
+ * This counter starts from 0 for every message passed to
+ * ::evmc_execute_fn.
+ * @param code_offset The current instruction position in the code.
* @param status_code The status code of the instruction execution.
* @param gas_left The amount of the gas left after the instruction execution.
- * @param stack_num_items The current EVM stack height.
+ * @param stack_num_items The current EVM stack height after the instruction execution.
* @param pushed_stack_item The top EVM stack item pushed as the result of the instruction
* execution. This value is null when the instruction does not push
* anything to the stack.
- * @param memory_size The current size of the EVM memory.
+ * @param memory_size The size of the EVM memory after the instruction execution.
* @param changed_memory_offset The beginning of the memory area modified as the result of
* the instruction execution.
* @param changed_memory_size The size of the memory area modified as the result of
@@ -745,9 +747,14 @@ typedef void (*evmc_trace_callback)(struct evmc_tracer_context* context,
* about instructions execution in the EVM.
* @see ::evmc_trace_callback.
*
+ * This will overwrite the previous settings (the callback and the context).
+ *
* @param instance The EVM instance.
- * @param callback The tracer callback function.
- * @param context The Client-side tracer context.
+ * @param callback The tracer callback function. This argument MAY be NULL to disable previously
+ * set tracer.
+ * @param context The Client-side tracer context. This argument MAY be NULL in case the tracer
+ * does not require any context. This argument MUST be NULL if the callback
+ * argument is NULL.
*/
typedef void (*evmc_set_tracer_fn)(struct evmc_instance* instance,
evmc_trace_callback callback,
