docs: natspec for HttpRequestModule (#131)

defi-wonderland · Sep 11, 2023 · cd75e3d · cd75e3d
1 parent bf14082
commit cd75e3d
Show file tree

Hide file tree

Showing 3 changed files with 46 additions and 11 deletions.
diff --git a/solidity/contracts/modules/HttpRequestModule.sol b/solidity/contracts/modules/HttpRequestModule.sol
@@ -2,15 +2,19 @@
 pragma solidity ^0.8.19;
 
 import {IERC20} from '@openzeppelin/contracts/token/ERC20/IERC20.sol';
-
 import {IHttpRequestModule} from '../../interfaces/modules/IHttpRequestModule.sol';
 import {IAccountingExtension} from '../../interfaces/extensions/IAccountingExtension.sol';
 import {IOracle} from '../../interfaces/IOracle.sol';
-import {IModule, Module} from '../Module.sol';
+import {Module} from '../Module.sol';
 
 contract HttpRequestModule is Module, IHttpRequestModule {
   constructor(IOracle _oracle) Module(_oracle) {}
 
+  function moduleName() public pure returns (string memory _moduleName) {
+    _moduleName = 'HttpRequestModule';
+  }
+
+  /// @inheritdoc IHttpRequestModule
   function decodeRequestData(bytes32 _requestId)
     public
     view
@@ -27,14 +31,18 @@ contract HttpRequestModule is Module, IHttpRequestModule {
       abi.decode(requestData[_requestId], (string, HttpMethod, string, IAccountingExtension, IERC20, uint256));
   }
 
-  function _afterSetupRequest(bytes32 _requestId, bytes calldata _data) internal override {
+  /**
+   * @notice Bonds the requester tokens to use as payment for the response proposer.
+   */
+  function _afterSetupRequest(bytes32 _requestId, bytes calldata) internal override {
     (,,, IAccountingExtension _accountingExtension, IERC20 _paymentToken, uint256 _paymentAmount) =
       decodeRequestData(_requestId);
     IOracle.Request memory _request = ORACLE.getRequest(_requestId);
     _accountingExtension.bond(_request.requester, _requestId, _paymentToken, _paymentAmount);
   }
 
-  function finalizeRequest(bytes32 _requestId, address) external override(IModule, Module) onlyOracle {
+  /// @inheritdoc IHttpRequestModule
+  function finalizeRequest(bytes32 _requestId, address) external override(IHttpRequestModule, Module) onlyOracle {
     IOracle.Request memory _request = ORACLE.getRequest(_requestId);
     IOracle.Response memory _response = ORACLE.getFinalizedResponse(_requestId);
     (,,, IAccountingExtension _accountingExtension, IERC20 _paymentToken, uint256 _paymentAmount) =
@@ -45,8 +53,4 @@ contract HttpRequestModule is Module, IHttpRequestModule {
       _accountingExtension.release(_request.requester, _requestId, _paymentToken, _paymentAmount);
     }
   }
-
-  function moduleName() public pure returns (string memory _moduleName) {
-    _moduleName = 'HttpRequestModule';
-  }
 }
diff --git a/solidity/interfaces/modules/IHttpRequestModule.sol b/solidity/interfaces/modules/IHttpRequestModule.sol
@@ -2,16 +2,40 @@
 pragma solidity ^0.8.19;
 
 import {IERC20} from '@openzeppelin/contracts/token/ERC20/IERC20.sol';
-
 import {IRequestModule} from '../../interfaces/modules/IRequestModule.sol';
 import {IAccountingExtension} from '../../interfaces/extensions/IAccountingExtension.sol';
 
+/*
+  * @title HttpRequestModule
+  * @notice Module allowing users to request HTTP calls 
+  */
 interface IHttpRequestModule is IRequestModule {
+  /*///////////////////////////////////////////////////////////////
+                              ENUMS
+  //////////////////////////////////////////////////////////////*/
+
+  /**
+   * @notice Available HTTP methods
+   */
   enum HttpMethod {
     GET,
     POST
   }
 
+  /*///////////////////////////////////////////////////////////////
+                              LOGIC
+  //////////////////////////////////////////////////////////////*/
+
+  /**
+   * @notice Returns the decoded data for a request
+   * @param _requestId The ID of the request
+   * @return _url The url to make the request to
+   * @return _method The HTTP method to use for the request
+   * @return _body The HTTP body to use for the request
+   * @return _accountingExtension The accounting extension used to bond and release tokens
+   * @return _paymentToken The token used to pay for the request
+   * @return _paymentAmount The amount of tokens to pay for the request
+   */
   function decodeRequestData(bytes32 _requestId)
     external
     view
@@ -23,4 +47,11 @@ interface IHttpRequestModule is IRequestModule {
       IERC20 _paymentToken,
       uint256 _paymentAmount
     );
+
+  /**
+   * @notice Finalizes a request by paying the proposer if there is a valid response
+   * or releases the requester bond if no valid response was provided
+   * @param _requestId The ID of the request
+   */
+  function finalizeRequest(bytes32 _requestId, address) external;
 }
diff --git a/solidity/test/unit/HttpRequestModule.t.sol b/solidity/test/unit/HttpRequestModule.t.sol
@@ -7,15 +7,15 @@ import 'forge-std/Test.sol';
 import {
   HttpRequestModule,
   IHttpRequestModule,
-  IModule,
   IOracle,
   IAccountingExtension,
   IERC20
 } from '../../contracts/modules/HttpRequestModule.sol';
-
+import {IModule} from '../../interfaces/IModule.sol';
 /**
  * @dev Harness to set an entry in the requestData mapping, without triggering setup request hooks
  */
+
 contract ForTest_HttpRequestModule is HttpRequestModule {
   constructor(IOracle _oracle) HttpRequestModule(_oracle) {}