From 53db5a036359bfc479d889888960a8de02675f99 Mon Sep 17 00:00:00 2001
From: Adam <lil22duckling@gmail.com>
Date: Thu, 23 Oct 2025 21:28:09 +0200
Subject: [PATCH] docs: add documentation for future interpreter API

Added missing documentation for all public APIs in the future interpreter module. This includes the FutureInterpreterAction trait, FutureInterpreterSubmit and FutureInterpreter structs, along with their public methods. The documentation follows the project's standards and provides clear explanations of parameters, return values, and usage patterns for async EVM operations.
---
 future/src/lib.rs | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/future/src/lib.rs b/future/src/lib.rs
index 5e8010aa..3e09e40a 100644
--- a/future/src/lib.rs
+++ b/future/src/lib.rs
@@ -1,4 +1,5 @@
 #![no_std]
+#![warn(missing_docs)]
 
 extern crate alloc;
 
@@ -14,10 +15,26 @@ use evm::interpreter::{
 	Capture, ExitError, ExitFatal, ExitResult, FeedbackInterpreter, Interpreter,
 };
 
+/// An action that can be executed by a future interpreter.
+///
+/// This trait defines the interface for asynchronous operations that can be
+/// submitted to a future interpreter. Implementations should handle the
+/// execution logic and return appropriate feedback or trap information.
 pub trait FutureInterpreterAction<S, H> {
+	/// The feedback type returned when the action completes successfully.
 	type Feedback;
+	/// The trap type that can be raised during action execution.
 	type Trap;
 
+	/// Execute the action with the given state, return buffer, and handler.
+	///
+	/// # Parameters
+	/// - `state`: Mutable reference to the interpreter state
+	/// - `retbuf`: Mutable reference to the return buffer
+	/// - `handle`: Mutable reference to the handler
+	///
+	/// # Returns
+	/// A `Capture` that either contains feedback on success or a trap on failure.
 	fn run(
 		self,
 		state: &mut S,
@@ -26,6 +43,11 @@ pub trait FutureInterpreterAction<S, H> {
 	) -> Capture<Self::Feedback, Self::Trap>;
 }
 
+/// A submitter for future interpreter actions.
+///
+/// This structure manages the submission and feedback mechanism for asynchronous
+/// actions in a future interpreter. It provides a way to submit actions and
+/// receive feedback through a future-based interface.
 pub struct FutureInterpreterSubmit<A, F> {
 	action: Cell<Option<A>>,
 	action_feedback: Cell<Option<F>>,
@@ -39,6 +61,13 @@ impl<A, F> FutureInterpreterSubmit<A, F> {
 		}
 	}
 
+	/// Submit an action for execution and return a future that resolves with feedback.
+	///
+	/// # Parameters
+	/// - `action`: The action to be executed
+	///
+	/// # Returns
+	/// A future that resolves with the feedback from the action execution.
 	pub fn submit(self: Rc<Self>, action: A) -> impl Future<Output = F> {
 		struct SubmitFuture<A, F>(Cell<Option<A>>, Rc<FutureInterpreterSubmit<A, F>>);
 
@@ -64,6 +93,11 @@ impl<A, F> FutureInterpreterSubmit<A, F> {
 	}
 }
 
+/// A future-based interpreter for asynchronous EVM operations.
+///
+/// This interpreter allows for asynchronous execution of EVM operations,
+/// particularly useful for async precompiles and other operations that
+/// require non-blocking execution.
 pub struct FutureInterpreter<A, F, S, Tr> {
 	state: S,
 	retbuf: Vec<u8>,
@@ -73,6 +107,15 @@ pub struct FutureInterpreter<A, F, S, Tr> {
 }
 
 impl<A, F, S, Tr> FutureInterpreter<A, F, S, Tr> {
+	/// Create a new future interpreter.
+	///
+	/// # Parameters
+	/// - `state`: The initial state for the interpreter
+	/// - `retbuf`: The return buffer for the interpreter
+	/// - `f`: A function that creates the future to be executed
+	///
+	/// # Returns
+	/// A new `FutureInterpreter` instance.
 	pub fn new<Fn, Fu>(state: S, retbuf: Vec<u8>, f: Fn) -> Self
 	where
 		Fn: FnOnce(Rc<FutureInterpreterSubmit<A, F>>) -> Fu,