From 6ce0907148b5e1a1efe7e4334d388ff9f25ce40c Mon Sep 17 00:00:00 2001
From: Gas One Cent <86567384+gas1cent@users.noreply.github.com>
Date: Sat, 11 Nov 2023 16:52:22 +0400
Subject: [PATCH] docs: natspec and documentation

---
 .../modules/resolution/arbitrator_module.md   | 10 ++---
 .../modules/resolution/IArbitratorModule.sol  | 42 ++++++++++---------
 2 files changed, 27 insertions(+), 25 deletions(-)

diff --git a/docs/src/content/modules/resolution/arbitrator_module.md b/docs/src/content/modules/resolution/arbitrator_module.md
index dac2c04c..a46327f6 100644
--- a/docs/src/content/modules/resolution/arbitrator_module.md
+++ b/docs/src/content/modules/resolution/arbitrator_module.md
@@ -10,11 +10,11 @@ The Arbitrator Module is a part of the dispute resolution system. It allows an e
 
 ### Key Methods
 
-- `getStatus(bytes32 _disputeId)`: Returns the arbitration status of a dispute.
-- `isValid(bytes32 _disputeId)`: Indicates whether the dispute has been arbitrated.
-- `startResolution(bytes32 _disputeId)`: Starts the arbitration process by calling `resolve` on the arbitrator and flags the dispute as `Active`.
-- `resolveDispute(bytes32 _disputeId)`: Resolves the dispute by getting the answer from the arbitrator and notifying the oracle.
-- `decodeRequestData(bytes calldata _data)`: Returns the decoded data for a request.
+- `getStatus`: Returns the arbitration status of a dispute.
+- `isValid`: Indicates whether the dispute has been arbitrated.
+- `startResolution`: Starts the arbitration process by calling `resolve` on the arbitrator and flags the dispute as `Active`.
+- `resolveDispute`: Resolves the dispute by getting the answer from the arbitrator and notifying the oracle.
+- `decodeRequestData`: Returns the decoded data for a request.
 
 ### Request Parameters
 
diff --git a/solidity/interfaces/modules/resolution/IArbitratorModule.sol b/solidity/interfaces/modules/resolution/IArbitratorModule.sol
index 17e9747d..3582fa54 100644
--- a/solidity/interfaces/modules/resolution/IArbitratorModule.sol
+++ b/solidity/interfaces/modules/resolution/IArbitratorModule.sol
@@ -7,19 +7,13 @@ import {IResolutionModule} from
 
 /*
   * @title ArbitratorModule
-  * @notice Module allowing an external arbitrator contract
-  * to resolve a dispute.
+  * @notice Module allowing an external arbitrator contract to resolve a dispute.
   */
 interface IArbitratorModule is IResolutionModule {
   /*///////////////////////////////////////////////////////////////
                               ERRORS
   //////////////////////////////////////////////////////////////*/
 
-  /**
-   * @notice Thrown when an unauthorized caller calls a function only the arbitrator can call
-   */
-  error ArbitratorModule_OnlyArbitrator();
-
   /**
    * @notice Thrown when trying to resolve a dispute that is not escalated
    */
@@ -63,19 +57,31 @@ interface IArbitratorModule is IResolutionModule {
                               LOGIC
   //////////////////////////////////////////////////////////////*/
 
+  /**
+   * @notice Returns the decoded data for a 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);
+
   /**
    * @notice Returns the current arbitration status of a dispute
+   *
    * @param _disputeId The ID of the dispute
    * @return _disputeStatus The `ArbitrationStatus` of the dispute
    */
   function getStatus(bytes32 _disputeId) external view returns (ArbitrationStatus _disputeStatus);
 
   /**
-   * @notice Starts the arbitration process by calling `resolve` on the
-   * arbitrator and flags the dispute as Active
+   * @notice Starts the arbitration process by calling `resolve` on the arbitrator and flags the dispute as Active
+   *
    * @dev Only callable by the Oracle
    * @dev Will revert if the arbitrator address is the address zero
-   * @param _disputeId The ID of the dispute
+   * @param _disputeId  The ID of the dispute
+   * @param _request    The request
+   * @param _response   The disputed response
+   * @param _dispute    The dispute being sent to the resolution
    */
   function startResolution(
     bytes32 _disputeId,
@@ -85,10 +91,13 @@ interface IArbitratorModule is IResolutionModule {
   ) external;
 
   /**
-   * @notice Resolves the dispute by getting the answer from the arbitrator
-   * and updating the dispute status
+   * @notice Resolves the dispute by getting the answer from the arbitrator and updating the dispute status
+   *
    * @dev Only callable by the Oracle
-   * @param _disputeId The ID of the dispute
+   * @param _disputeId  The ID of the dispute
+   * @param _request    The request
+   * @param _response   The disputed response
+   * @param _dispute    The dispute that is being resolved
    */
   function resolveDispute(
     bytes32 _disputeId,
@@ -96,11 +105,4 @@ interface IArbitratorModule is IResolutionModule {
     IOracle.Response calldata _response,
     IOracle.Dispute calldata _dispute
   ) external;
-
-  /**
-   * @notice Returns the decoded data for a 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);
 }