docs: natspec and documentation

defi-wonderland · Nov 11, 2023 · 6ce0907 · 6ce0907
1 parent df7c66e
commit 6ce0907
Show file tree

Hide file tree

Showing 2 changed files with 27 additions and 25 deletions.
diff --git 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
@@ -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,22 +91,18 @@ 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,
     IOracle.Request calldata _request,
     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);
 }