Streamline comments and errors (#528)

### Description

Fixes mento-protocol/mento-general#552

- [x] Made error messages across GoodDollar contracts more consistent
- [x] Made comments across GoodDollar comments more consistent
- [x] Introduced @inheritdoc to reduce comment duplication between
interfaces and implementations in 0.8 contracts
- [x] Changed `Broker.configureTradingLimit()` from ~~public~~ to
**external**

contracts/goodDollar/GoodDollarExchangeProvider.sol

@@ -14,7 +14,9 @@ import { UD60x18, unwrap, wrap } from "prb/math/UD60x18.sol";
  * @notice Provides exchange functionality for the GoodDollar system.
  */
 contract GoodDollarExchangeProvider is IGoodDollarExchangeProvider, BancorExchangeProvider, PausableUpgradeable {
+  /* ========================================================= */
   /* ==================== State Variables ==================== */
+  /* ========================================================= */
 
   // Address of the Expansion Controller contract.
   IGoodDollarExpansionController public expansionController;
@@ -23,25 +25,19 @@ contract GoodDollarExchangeProvider is IGoodDollarExchangeProvider, BancorExchan
   // solhint-disable-next-line var-name-mixedcase
   address public AVATAR;
 
+  /* ===================================================== */
   /* ==================== Constructor ==================== */
+  /* ===================================================== */
 
   /**
-   * @dev Should be called with disable=true in deployments when
-   * it's accessed through a Proxy.
-   * Call this with disable=false during testing, when used
-   * without a proxy.
+   * @dev Should be called with disable=true in deployments when it's accessed through a Proxy.
+   * Call this with disable=false during testing, when used without a proxy.
    * @param disable Set to true to run `_disableInitializers()` inherited from
    * openzeppelin-contracts-upgradeable/Initializable.sol
    */
   constructor(bool disable) BancorExchangeProvider(disable) {}
 
-  /**
-   * @notice Initializes the contract with the given parameters.
-   * @param _broker The address of the Broker contract.
-   * @param _reserve The address of the Reserve contract.
-   * @param _expansionController The address of the ExpansionController contract.
-   * @param _avatar The address of the GoodDollar DAO contract.
-   */
+  /// @inheritdoc IGoodDollarExchangeProvider
   function initialize(
     address _broker,
     address _reserve,
@@ -55,7 +51,9 @@ contract GoodDollarExchangeProvider is IGoodDollarExchangeProvider, BancorExchan
     setAvatar(_avatar);
   }
 
+  /* =================================================== */
   /* ==================== Modifiers ==================== */
+  /* =================================================== */
 
   modifier onlyAvatar() {
     require(msg.sender == AVATAR, "Only Avatar can call this function");
@@ -67,47 +65,43 @@ contract GoodDollarExchangeProvider is IGoodDollarExchangeProvider, BancorExchan
     _;
   }
 
+  /* ============================================================ */
   /* ==================== Mutative Functions ==================== */
+  /* ============================================================ */
 
-  /**
-   * @notice Sets the address of the GoodDollar DAO contract.
-   * @param _avatar The address of the DAO contract.
-   */
+  /// @inheritdoc IGoodDollarExchangeProvider
   function setAvatar(address _avatar) public onlyOwner {
     require(_avatar != address(0), "Avatar address must be set");
     AVATAR = _avatar;
     emit AvatarUpdated(_avatar);
   }
 
-  /**
-   * @notice Sets the address of the Expansion Controller contract.
-   * @param _expansionController The address of the Expansion Controller contract.
-   */
+  /// @inheritdoc IGoodDollarExchangeProvider
   function setExpansionController(address _expansionController) public onlyOwner {
     require(_expansionController != address(0), "ExpansionController address must be set");
     expansionController = IGoodDollarExpansionController(_expansionController);
     emit ExpansionControllerUpdated(_expansionController);
   }
 
   /**
-   * @notice Sets the exit contribution for a pool. Only callable by the Avatar.
    * @inheritdoc BancorExchangeProvider
+   * @dev Only callable by the GoodDollar DAO contract.
    */
   function setExitContribution(bytes32 exchangeId, uint32 exitContribution) external override onlyAvatar {
     return _setExitContribution(exchangeId, exitContribution);
   }
 
   /**
-   * @notice Creates a new exchange. Only callable by the Avatar.
    * @inheritdoc BancorExchangeProvider
+   * @dev Only callable by the GoodDollar DAO contract.
    */
   function createExchange(PoolExchange calldata _exchange) external override onlyAvatar returns (bytes32 exchangeId) {
     return _createExchange(_exchange);
   }
 
   /**
-   * @notice Destroys an exchange. Only callable by the Avatar.
    * @inheritdoc BancorExchangeProvider
+   * @dev Only callable by the GoodDollar DAO contract.
    */
   function destroyExchange(
     bytes32 exchangeId,
@@ -116,14 +110,7 @@ contract GoodDollarExchangeProvider is IGoodDollarExchangeProvider, BancorExchan
     return _destroyExchange(exchangeId, exchangeIdIndex);
   }
 
-  /**
-   * @notice Execute a token swap with fixed amountIn
-   * @param exchangeId The id of exchange, i.e. PoolExchange to use
-   * @param tokenIn The token to be sold
-   * @param tokenOut The token to be bought
-   * @param amountIn The amount of tokenIn to be sold
-   * @return amountOut The amount of tokenOut to be bought
-   */
+  /// @inheritdoc BancorExchangeProvider
   function swapIn(
     bytes32 exchangeId,
     address tokenIn,
@@ -133,14 +120,7 @@ contract GoodDollarExchangeProvider is IGoodDollarExchangeProvider, BancorExchan
     amountOut = BancorExchangeProvider.swapIn(exchangeId, tokenIn, tokenOut, amountIn);
   }
 
-  /**
-   * @notice Execute a token swap with fixed amountOut
-   * @param exchangeId The id of exchange, i.e. PoolExchange to use
-   * @param tokenIn The token to be sold
-   * @param tokenOut The token to be bought
-   * @param amountOut The amount of tokenOut to be bought
-   * @return amountIn The amount of tokenIn to be sold
-   */
+  /// @inheritdoc BancorExchangeProvider
   function swapOut(
     bytes32 exchangeId,
     address tokenIn,
@@ -151,13 +131,10 @@ contract GoodDollarExchangeProvider is IGoodDollarExchangeProvider, BancorExchan
   }
 
   /**
-   * @notice Calculates the amount of tokens to be minted as a result of expansion.
-   * @dev Calculates the amount of tokens that need to be minted as a result of the expansion
+   * @inheritdoc IGoodDollarExchangeProvider
+   * @dev Calculates the amount of G$ tokens that need to be minted as a result of the expansion
    *      while keeping the current price the same.
    *      calculation: amountToMint = (tokenSupply * reserveRatio - tokenSupply * newRatio) / newRatio
-   * @param exchangeId The id of the pool to calculate expansion for.
-   * @param expansionScaler Scaler for calculating the new reserve ratio.
-   * @return amountToMint amount of tokens to be minted as a result of the expansion.
    */
   function mintFromExpansion(
     bytes32 exchangeId,
@@ -180,17 +157,15 @@ contract GoodDollarExchangeProvider is IGoodDollarExchangeProvider, BancorExchan
 
     amountToMint = scaledAmountToMint / tokenPrecisionMultipliers[exchange.tokenAddress];
     emit ReserveRatioUpdated(exchangeId, newRatioUint);
+
     return amountToMint;
   }
 
   /**
-   * @notice Calculates the amount of tokens to be minted as a result of collecting the reserve interest.
-   * @dev Calculates the amount of tokens that need to be minted as a result of the reserve interest
+   * @inheritdoc IGoodDollarExchangeProvider
+   * @dev Calculates the amount of G$ tokens that need to be minted as a result of the reserve interest
    *      flowing into the reserve while keeping the current price the same.
    *      calculation: amountToMint = reserveInterest * tokenSupply / reserveBalance
-   * @param exchangeId The id of the pool the reserve interest is added to.
-   * @param reserveInterest The amount of reserve tokens collected from interest.
-   * @return amountToMint amount of tokens to be minted as a result of the reserve interest.
    */
   function mintFromInterest(
     bytes32 exchangeId,
@@ -211,11 +186,9 @@ contract GoodDollarExchangeProvider is IGoodDollarExchangeProvider, BancorExchan
   }
 
   /**
-   * @notice Calculates the reserve ratio needed to mint the reward.
-   * @dev Calculates the new reserve ratio needed to mint the reward while keeping the current price the same.
+   * @inheritdoc IGoodDollarExchangeProvider
+   * @dev Calculates the new reserve ratio needed to mint the G$ reward while keeping the current price the same.
    *      calculation: newRatio = reserveBalance / (tokenSupply + reward) * currentPrice
-   * @param exchangeId The id of the pool the reward is minted from.
-   * @param reward The amount of tokens to be minted as a reward.
    */
   function updateRatioForReward(bytes32 exchangeId, uint256 reward) external onlyExpansionController whenNotPaused {
     PoolExchange memory exchange = getPoolExchange(exchangeId);
@@ -239,16 +212,16 @@ contract GoodDollarExchangeProvider is IGoodDollarExchangeProvider, BancorExchan
   }
 
   /**
-   * @notice Pauses the contract.
-   * @dev Functions is only callable by the GoodDollar DAO contract.
+   * @inheritdoc IGoodDollarExchangeProvider
+   * @dev Only callable by the GoodDollar DAO contract.
    */
   function pause() external virtual onlyAvatar {
     _pause();
   }
 
   /**
-   * @notice Unpauses the contract.
-   * @dev Functions is only callable by the GoodDollar DAO contract.
+   * @inheritdoc IGoodDollarExchangeProvider
+   * @dev Only callable by the GoodDollar DAO contract.
    */
   function unpause() external virtual onlyAvatar {
     _unpause();