From 5ed765165f9f065a21f83e4a470b5cd32b55781e Mon Sep 17 00:00:00 2001
From: Gas One Cent <86567384+gas1cent@users.noreply.github.com>
Date: Sat, 11 Nov 2023 20:21:09 +0400
Subject: [PATCH] docs: review natspec and documentation

---
 .../sparse_merkle_tree_request_module.md      |  6 +++---
 .../ISparseMerkleTreeRequestModule.sol        | 19 +++++++++++++------
 2 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/docs/src/content/modules/request/sparse_merkle_tree_request_module.md b/docs/src/content/modules/request/sparse_merkle_tree_request_module.md
index 44fc3060..3968ba90 100644
--- a/docs/src/content/modules/request/sparse_merkle_tree_request_module.md
+++ b/docs/src/content/modules/request/sparse_merkle_tree_request_module.md
@@ -10,8 +10,8 @@ The `SparseMerkleTreeRequestModule` is a contract that allows a user to request
 
 ### Key Methods
 
-- `decodeRequestData(bytes calldata _data)`: This function decodes the request data for a given request ID. It returns a RequestParameters struct that contains the parameters for the request.
-- `finalizeRequest(bytes32 _requestId, address _finalizer)`: This function is called by the Oracle to finalize the request. It either pays the proposer for the response or releases the requester's bond if no response was submitted.
+- `decodeRequestData`: This function decodes the request data for a given request ID. It returns a RequestParameters struct that contains the parameters for the request.
+- `finalizeRequest`: This function is called by the Oracle to finalize the request. It either pays the proposer for the response or releases the requester's bond if no response was submitted.
 
 ### Request Parameters
 
@@ -28,5 +28,5 @@ The `SparseMerkleTreeRequestModule` uses a Merkle tree to calculate the root fro
 
 ## 4. Gotchas
 
-- The module is supposed to be paired with the root verification module.
+- The module is supposed to be paired with [`RootVerificationModule`](../dispute/root_verification_module.md).
 - The verifier contract must follow the `ITreeVerifier` interface, otherwise the proposers won't be able to calculate the correct response.
diff --git a/solidity/interfaces/modules/request/ISparseMerkleTreeRequestModule.sol b/solidity/interfaces/modules/request/ISparseMerkleTreeRequestModule.sol
index 8357ee8e..7add6179 100644
--- a/solidity/interfaces/modules/request/ISparseMerkleTreeRequestModule.sol
+++ b/solidity/interfaces/modules/request/ISparseMerkleTreeRequestModule.sol
@@ -43,20 +43,27 @@ interface ISparseMerkleTreeRequestModule is IRequestModule {
 
   /**
    * @notice Returns the decoded data for a request
-   * @param _data The encoded request parameters
-   * @return _params The struct containing the parameters for the request
+   *
+   * @param _data     The encoded request parameters
+   * @return _params  The struct containing the parameters for the request
    */
   function decodeRequestData(bytes calldata _data) external view returns (RequestParameters memory _params);
 
-  /// @inheritdoc IRequestModule
+  /**
+   * @notice Executes pre-request logic, bonding the requester's funds
+   *
+   * @param _requestId  The id of the request
+   * @param _data       The encoded request parameters
+   * @param _requester  The user who triggered the request
+   */
   function createRequest(bytes32 _requestId, bytes calldata _data, address _requester) external;
 
   /**
    * @notice Finalizes the request by paying the proposer for the response or releasing the requester's bond if no response was submitted
    *
-   * @param _request The request that is being finalized
-   * @param _response The final response
-   * @param _finalizer The user who triggered the finalization
+   * @param _request    The request that is being finalized
+   * @param _response   The final response
+   * @param _finalizer  The user who triggered the finalization
    */
   function finalizeRequest(
     IOracle.Request calldata _request,