Add missing docs on interfaces and modules (#1745)

* Add missing docs on interfaces and modules

* Update markets/perps-market/contracts/interfaces/IPerpsMarketFactoryModule.sol

Co-authored-by: troy (troyb.eth) <[email protected]>

* pr review -> size in `units of native asset`

* docgen

---------

Co-authored-by: troy (troyb.eth) <[email protected]>

docs/Contracts.md

@@ -3830,7 +3830,7 @@ There is a synthetix v3 core system supply cap also set. If the current supply b
 #### computeOrderFees
 
   ```solidity
-  function computeOrderFees(uint128 marketId, int128 sizeDelta) external view returns (uint256 orderFees)
+  function computeOrderFees(uint128 marketId, int128 sizeDelta) external view returns (uint256 orderFees, uint256 fillPrice)
   ```
 
   Simulates what the order fee would be for the given market with the specified size.
@@ -3843,6 +3843,24 @@ There is a synthetix v3 core system supply cap also set. If the current supply b
 
 **Returns**
 * `orderFees` (*uint256*) - incurred fees.
+* `fillPrice` (*uint256*) - price at which the order would be filled.
+#### requiredMarginForOrder
+
+  ```solidity
+  function requiredMarginForOrder(uint128 marketId, uint128 accountId, int128 sizeDelta) external view returns (uint256 requiredMargin)
+  ```
+
+  For a given market, account id, and a position size, returns the required total account margin for this order to succeed
+
+  Useful for integrators to determine if an order will succeed or fail
+
+**Parameters**
+* `marketId` (*uint128*) - id of the market.
+* `accountId` (*uint128*) - id of the trader account.
+* `sizeDelta` (*int128*) - size of position.
+
+**Returns**
+* `requiredMargin` (*uint256*) - margin required for the order to succeed.
 
 #### OrderCommitted
 
@@ -3863,6 +3881,22 @@ There is a synthetix v3 core system supply cap also set. If the current supply b
 * `trackingCode` (*bytes32*) - Optional code for integrator tracking purposes.
 * `sender` (*address*) - address of the sender of the order. Authorized to commit by account owner.
 
+#### PreviousOrderExpired
+
+  ```solidity
+  event PreviousOrderExpired(uint128 marketId, uint128 accountId, int128 sizeDelta, uint256 acceptablePrice, uint256 settlementTime, bytes32 trackingCode)
+  ```
+
+  Gets fired when a new order is committed while a previous one was expired.
+
+**Parameters**
+* `marketId` (*uint128*) - Id of the market used for the trade.
+* `accountId` (*uint128*) - Id of the account used for the trade.
+* `sizeDelta` (*int128*) - requested change in size of the order sent by the user.
+* `acceptablePrice` (*uint256*) - maximum or minimum, depending on the sizeDelta direction, accepted price to settle the order, set by the user.
+* `settlementTime` (*uint256*) - Time at which the order can be settled.
+* `trackingCode` (*bytes32*) - Optional code for integrator tracking purposes.
+
 ### Async Order Settlement Module
 
 #### settle
@@ -4147,24 +4181,50 @@ There is a synthetix v3 core system supply cap also set. If the current supply b
   function liquidate(uint128 accountId) external
   ```
 
+  Liquidates an account.
+
+  according to the current situation and account size it can be a partial or full liquidation.
+
+**Parameters**
+* `accountId` (*uint128*) - Id of the account to liquidate.
+
 #### liquidateFlagged
 
   ```solidity
   function liquidateFlagged() external
   ```
 
+  Liquidates all flagged accounts.
+
 #### PositionLiquidated
 
   ```solidity
   event PositionLiquidated(uint128 accountId, uint128 marketId, uint256 amountLiquidated, int128 currentPositionSize)
   ```
 
+  Gets fired when an account position is liquidated .
+
+**Parameters**
+* `accountId` (*uint128*) - Id of the account liquidated.
+* `marketId` (*uint128*) - Id of the position's market.
+* `amountLiquidated` (*uint256*) - amount liquidated.
+* `currentPositionSize` (*int128*) - position size after liquidation.
+
 #### AccountLiquidated
 
   ```solidity
   event AccountLiquidated(uint128 accountId, uint256 reward, bool fullLiquidation)
   ```
 
+  Gets fired when an account is liquidated.
+
+  this event is fired once per liquidation tx after the each position that can be liquidated at the time was liquidated.
+
+**Parameters**
+* `accountId` (*uint128*) - Id of the account liquidated.
+* `reward` (*uint256*) - total reward sent to liquidator.
+* `fullLiquidation` (*bool*) - flag indicating if it was a partial or full liquidation.
+
 ### Market Configuration Module
 
 #### addSettlementStrategy
@@ -4625,24 +4685,49 @@ There is a synthetix v3 core system supply cap also set. If the current supply b
   function initializeFactory() external returns (uint128)
   ```
 
+  Initializes the factory.
+
+  this function should be called only once.
+
+**Returns**
+* `[0]` (*uint128*) - globalPerpsMarketId Id of the global perps market id.
 #### setSynthetix
 
   ```solidity
   function setSynthetix(contract ISynthetixSystem synthetix) external
   ```
 
+  Sets the synthetix system.
+
+**Parameters**
+* `synthetix` (*contract ISynthetixSystem*) - address of the main synthetix proxy.
+
 #### setSpotMarket
 
   ```solidity
   function setSpotMarket(contract ISpotMarketSystem spotMarket) external
   ```
 
+  Sets the spot market system.
+
+**Parameters**
+* `spotMarket` (*contract ISpotMarketSystem*) - address of the spot market proxy.
+
 #### createMarket
 
   ```solidity
   function createMarket(uint128 requestedMarketId, string marketName, string marketSymbol) external returns (uint128)
   ```
 
+  Creates a new market.
+
+**Parameters**
+* `requestedMarketId` (*uint128*) - id of the market to create.
+* `marketName` (*string*) - name of the market to create.
+* `marketSymbol` (*string*) - symbol of the market to create.
+
+**Returns**
+* `[0]` (*uint128*) - perpsMarketId Id of the created perps market.
 #### name
 
   ```solidity
@@ -4687,12 +4772,24 @@ There is a synthetix v3 core system supply cap also set. If the current supply b
   event FactoryInitialized(uint128 globalPerpsMarketId)
   ```
 
+  Gets fired when the factory is initialized.
+
+**Parameters**
+* `globalPerpsMarketId` (*uint128*) - the new global perps market id.
+
 #### MarketCreated
 
   ```solidity
   event MarketCreated(uint128 perpsMarketId, string marketName, string marketSymbol)
   ```
 
+  Gets fired when a market is created.
+
+**Parameters**
+* `perpsMarketId` (*uint128*) - the newly created perps market id.
+* `marketName` (*string*) - the newly created perps market name.
+* `marketSymbol` (*string*) - the newly created perps market symbol.
+
 ### Perps Market Module
 
 #### metadata
@@ -4701,48 +4798,107 @@ There is a synthetix v3 core system supply cap also set. If the current supply b
   function metadata(uint128 marketId) external view returns (string name, string symbol)
   ```
 
+  Gets a market metadata.
+
+**Parameters**
+* `marketId` (*uint128*) - Id of the market.
+
+**Returns**
+* `name` (*string*) - Name of the market.
+* `symbol` (*string*) - Symbol of the market.
 #### skew
 
   ```solidity
   function skew(uint128 marketId) external view returns (int256)
   ```
 
+  Gets a market's skew.
+
+**Parameters**
+* `marketId` (*uint128*) - Id of the market.
+
+**Returns**
+* `[0]` (*int256*) - skew Skew of the market.
 #### size
 
   ```solidity
   function size(uint128 marketId) external view returns (uint256)
   ```
 
+  Gets a market's size.
+
+**Parameters**
+* `marketId` (*uint128*) - Id of the market.
+
+**Returns**
+* `[0]` (*uint256*) - size Size of the market.
 #### maxOpenInterest
 
   ```solidity
   function maxOpenInterest(uint128 marketId) external view returns (uint256)
   ```
 
+  Gets a market's max open interest.
+
+**Parameters**
+* `marketId` (*uint128*) - Id of the market.
+
+**Returns**
+* `[0]` (*uint256*) - maxOpenInterest Max open interest of the market.
 #### currentFundingRate
 
   ```solidity
   function currentFundingRate(uint128 marketId) external view returns (int256)
   ```
 
+  Gets a market's current funding rate.
+
+**Parameters**
+* `marketId` (*uint128*) - Id of the market.
+
+**Returns**
+* `[0]` (*int256*) - currentFundingRate Current funding rate of the market.
 #### currentFundingVelocity
 
   ```solidity
   function currentFundingVelocity(uint128 marketId) external view returns (int256)
   ```
 
+  Gets a market's current funding velocity.
+
+**Parameters**
+* `marketId` (*uint128*) - Id of the market.
+
+**Returns**
+* `[0]` (*int256*) - currentFundingVelocity Current funding velocity of the market.
 #### indexPrice
 
   ```solidity
   function indexPrice(uint128 marketId) external view returns (uint256)
   ```
 
+  Gets a market's index price.
+
+**Parameters**
+* `marketId` (*uint128*) - Id of the market.
+
+**Returns**
+* `[0]` (*uint256*) - indexPrice Index price of the market.
 #### fillPrice
 
   ```solidity
   function fillPrice(uint128 marketId, int128 orderSize, uint256 price) external returns (uint256)
   ```
 
+  Gets a market's fill price for a specific order size and index price.
+
+**Parameters**
+* `marketId` (*uint128*) - Id of the market.
+* `orderSize` (*int128*) - Order size.
+* `price` (*uint256*) - Index price.
+
+**Returns**
+* `[0]` (*uint256*) - price Fill price.
 #### getMarketSummary
 
   ```solidity
@@ -4751,6 +4907,12 @@ There is a synthetix v3 core system supply cap also set. If the current supply b
 
   Given a marketId return a market's summary details in one call.
 
+**Parameters**
+* `marketId` (*uint128*) - Id of the market.
+
+**Returns**
+* `summary` (*struct IPerpsMarketModule.MarketSummary*) - Market summary (see MarketSummary).
+
 ## Governance
 
 - [Back to TOC](#smart-contracts)

markets/perps-market/contracts/interfaces/ILiquidationModule.sol

@@ -1,19 +1,47 @@
 //SPDX-License-Identifier: MIT
 pragma solidity >=0.8.11 <0.9.0;
 
+/**
+ * @title Liquidation module
+ */
 interface ILiquidationModule {
+    /**
+     * @notice Thrown when attempting to liquidate an account not elegible for liquidation
+     */
     error NotEligibleForLiquidation(uint128 accountId);
 
+    /**
+     * @notice Gets fired when an account position is liquidated .
+     * @param marketId Id of the position's market.
+     * @param accountId Id of the account liquidated.
+     * @param amountLiquidated amount liquidated.
+     * @param currentPositionSize position size after liquidation.
+     */
     event PositionLiquidated(
         uint128 indexed accountId,
         uint128 indexed marketId,
         uint256 amountLiquidated,
         int128 currentPositionSize
     );
 
+    /**
+     * @notice Gets fired when an account is liquidated.
+     * @dev this event is fired once per liquidation tx after the each position that can be liquidated at the time was liquidated.
+     * @param accountId Id of the account liquidated.
+     * @param reward total reward sent to liquidator.
+     * @param fullLiquidation flag indicating if it was a partial or full liquidation.
+     */
     event AccountLiquidated(uint128 indexed accountId, uint256 reward, bool fullLiquidation);
 
+    /**
+     * @notice Liquidates an account.
+     * @dev according to the current situation and account size it can be a partial or full liquidation.
+     * @param accountId Id of the account to liquidate.
+     */
     function liquidate(uint128 accountId) external;
 
+    /**
+     * @notice Liquidates all flagged accounts.
+     */
     function liquidateFlagged() external;
 }

markets/perps-market/contracts/interfaces/IMarketEvents.sol

@@ -1,6 +1,9 @@
 //SPDX-License-Identifier: MIT
 pragma solidity >=0.8.11 <0.9.0;
 
+/**
+ * @title Market events used on several places in the system.
+ */
 interface IMarketEvents {
     /**
      * @notice Gets fired when the size of a market is updated by new orders or liquidations.