diff --git a/docs/Contracts.md b/docs/Contracts.md
index e37b0fc77d..909f6f220b 100644
--- a/docs/Contracts.md
+++ b/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)
diff --git a/markets/perps-market/contracts/interfaces/ILiquidationModule.sol b/markets/perps-market/contracts/interfaces/ILiquidationModule.sol
index 0dabb49e0d..efbee7f8a8 100644
--- a/markets/perps-market/contracts/interfaces/ILiquidationModule.sol
+++ b/markets/perps-market/contracts/interfaces/ILiquidationModule.sol
@@ -1,9 +1,22 @@
 //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,
@@ -11,9 +24,24 @@ interface ILiquidationModule {
         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;
 }
diff --git a/markets/perps-market/contracts/interfaces/IMarketEvents.sol b/markets/perps-market/contracts/interfaces/IMarketEvents.sol
index adf02e7144..862dfd43a1 100644
--- a/markets/perps-market/contracts/interfaces/IMarketEvents.sol
+++ b/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.
diff --git a/markets/perps-market/contracts/interfaces/IPerpsMarketFactoryModule.sol b/markets/perps-market/contracts/interfaces/IPerpsMarketFactoryModule.sol
index c35ec33f9d..8c86bd45f3 100644
--- a/markets/perps-market/contracts/interfaces/IPerpsMarketFactoryModule.sol
+++ b/markets/perps-market/contracts/interfaces/IPerpsMarketFactoryModule.sol
@@ -5,16 +5,50 @@ import {IMarket} from "@synthetixio/main/contracts/interfaces/external/IMarket.s
 import {ISynthetixSystem} from "./external/ISynthetixSystem.sol";
 import {ISpotMarketSystem} from "./external/ISpotMarketSystem.sol";
 
+/**
+ * @title Perps Market Factory module
+ */
 interface IPerpsMarketFactoryModule is IMarket {
+    /**
+     * @notice Gets fired when the factory is initialized.
+     * @param globalPerpsMarketId the new global perps market id.
+     */
     event FactoryInitialized(uint128 globalPerpsMarketId);
+
+    /**
+     * @notice Gets fired when a market is created.
+     * @param perpsMarketId the newly created perps market id.
+     * @param marketName the newly created perps market name.
+     * @param marketSymbol the newly created perps market symbol.
+     */
     event MarketCreated(uint128 indexed perpsMarketId, string marketName, string marketSymbol);
 
+    /**
+     * @notice Initializes the factory.
+     * @dev this function should be called only once.
+     * @return globalPerpsMarketId Id of the global perps market id.
+     */
     function initializeFactory() external returns (uint128);
 
+    /**
+     * @notice Sets the synthetix system.
+     * @param synthetix address of the main synthetix proxy.
+     */
     function setSynthetix(ISynthetixSystem synthetix) external;
 
+    /**
+     * @notice Sets the spot market system.
+     * @param spotMarket address of the spot market proxy.
+     */
     function setSpotMarket(ISpotMarketSystem spotMarket) external;
 
+    /**
+     * @notice Creates a new market.
+     * @param requestedMarketId id of the market to create.
+     * @param marketName name of the market to create.
+     * @param marketSymbol symbol of the market to create.
+     * @return perpsMarketId Id of the created perps market.
+     */
     function createMarket(
         uint128 requestedMarketId,
         string memory marketName,
diff --git a/markets/perps-market/contracts/interfaces/IPerpsMarketModule.sol b/markets/perps-market/contracts/interfaces/IPerpsMarketModule.sol
index c50666862d..182b8b914e 100644
--- a/markets/perps-market/contracts/interfaces/IPerpsMarketModule.sol
+++ b/markets/perps-market/contracts/interfaces/IPerpsMarketModule.sol
@@ -5,35 +5,89 @@ pragma solidity >=0.8.11 <0.9.0;
  * @title Perps market module
  */
 interface IPerpsMarketModule {
+    /**
+     * @notice Market Summary structured data.
+     */
     struct MarketSummary {
+        // @dev Skew of the market in units of native asse
         int256 skew;
+        // @dev Size of the market in units of native asset
         uint256 size;
+        // @dev Max open interest of the market in units of native asset
         uint256 maxOpenInterest;
+        // @dev Current funding rate of the market
         int currentFundingRate;
+        // @dev Current funding velocity of the market
         int currentFundingVelocity;
+        // @dev Index price of the market
         uint indexPrice;
     }
 
+    /**
+     * @notice Gets a market metadata.
+     * @param marketId Id of the market.
+     * @return name Name of the market.
+     * @return symbol Symbol of the market.
+     */
     function metadata(
         uint128 marketId
     ) external view returns (string memory name, string memory symbol);
 
+    /**
+     * @notice Gets a market's skew.
+     * @param marketId Id of the market.
+     * @return skew Skew of the market.
+     */
     function skew(uint128 marketId) external view returns (int256);
 
+    /**
+     * @notice Gets a market's size.
+     * @param marketId Id of the market.
+     * @return size Size of the market.
+     */
     function size(uint128 marketId) external view returns (uint256);
 
+    /**
+     * @notice Gets a market's max open interest.
+     * @param marketId Id of the market.
+     * @return maxOpenInterest Max open interest of the market.
+     */
     function maxOpenInterest(uint128 marketId) external view returns (uint256);
 
+    /**
+     * @notice Gets a market's current funding rate.
+     * @param marketId Id of the market.
+     * @return currentFundingRate Current funding rate of the market.
+     */
     function currentFundingRate(uint128 marketId) external view returns (int);
 
+    /**
+     * @notice Gets a market's current funding velocity.
+     * @param marketId Id of the market.
+     * @return currentFundingVelocity Current funding velocity of the market.
+     */
     function currentFundingVelocity(uint128 marketId) external view returns (int);
 
+    /**
+     * @notice Gets a market's index price.
+     * @param marketId Id of the market.
+     * @return indexPrice Index price of the market.
+     */
     function indexPrice(uint128 marketId) external view returns (uint);
 
+    /**
+     * @notice Gets a market's fill price for a specific order size and index price.
+     * @param marketId Id of the market.
+     * @param orderSize Order size.
+     * @param price Index price.
+     * @return price Fill price.
+     */
     function fillPrice(uint128 marketId, int128 orderSize, uint price) external returns (uint);
 
     /**
-     * @dev Given a marketId return a market's summary details in one call.
+     * @notice Given a marketId return a market's summary details in one call.
+     * @param marketId Id of the market.
+     * @return summary Market summary (see MarketSummary).
      */
     function getMarketSummary(
         uint128 marketId
diff --git a/markets/perps-market/contracts/mocks/FeeCollectorMock.sol b/markets/perps-market/contracts/mocks/FeeCollectorMock.sol
index 545e2b3faf..d48ac491f7 100644
--- a/markets/perps-market/contracts/mocks/FeeCollectorMock.sol
+++ b/markets/perps-market/contracts/mocks/FeeCollectorMock.sol
@@ -3,6 +3,9 @@ pragma solidity >=0.8.11 <0.9.0;
 
 import "../interfaces/external/IFeeCollector.sol";
 
+/**
+ * @title Mock Fee Collector.
+ */
 contract FeeCollectorMock is IFeeCollector {
     uint internal feeRatioD18;
 
diff --git a/markets/perps-market/contracts/mocks/MockPyth.sol b/markets/perps-market/contracts/mocks/MockPyth.sol
index fcd59c605a..dc0e540d29 100644
--- a/markets/perps-market/contracts/mocks/MockPyth.sol
+++ b/markets/perps-market/contracts/mocks/MockPyth.sol
@@ -4,7 +4,7 @@ pragma solidity >=0.8.11 <0.9.0;
 import {MockPyth as BaseMockPyth} from "@synthetixio/oracle-manager/contracts/mocks/pyth/MockPyth.sol";
 
 /**
- * @title Module for connecting to other systems.
+ * @title Mocked Pyth.
  * See oracle-manager/../MockPyth
  */
 contract MockPyth is BaseMockPyth {
diff --git a/markets/perps-market/contracts/modules/AsyncOrderModule.sol b/markets/perps-market/contracts/modules/AsyncOrderModule.sol
index c855acb6bd..5375b88e34 100644
--- a/markets/perps-market/contracts/modules/AsyncOrderModule.sol
+++ b/markets/perps-market/contracts/modules/AsyncOrderModule.sol
@@ -16,7 +16,7 @@ import {PerpsMarketConfiguration} from "../storage/PerpsMarketConfiguration.sol"
 import {SettlementStrategy} from "../storage/SettlementStrategy.sol";
 
 /**
- * @title Module for committing and settling async orders.
+ * @title Module for committing async orders.
  * @dev See IAsyncOrderModule.
  */
 contract AsyncOrderModule is IAsyncOrderModule {
diff --git a/markets/perps-market/contracts/modules/AsyncOrderSettlementModule.sol b/markets/perps-market/contracts/modules/AsyncOrderSettlementModule.sol
index 1b55d8ef69..002151bbf7 100644
--- a/markets/perps-market/contracts/modules/AsyncOrderSettlementModule.sol
+++ b/markets/perps-market/contracts/modules/AsyncOrderSettlementModule.sol
@@ -17,6 +17,10 @@ import {PerpsMarketFactory} from "../storage/PerpsMarketFactory.sol";
 import {GlobalPerpsMarketConfiguration} from "../storage/GlobalPerpsMarketConfiguration.sol";
 import {IMarketEvents} from "../interfaces/IMarketEvents.sol";
 
+/**
+ * @title Module for settling async orders.
+ * @dev See IAsyncOrderSettlementModule.
+ */
 contract AsyncOrderSettlementModule is IAsyncOrderSettlementModule, IMarketEvents {
     using DecimalMath for int256;
     using DecimalMath for uint256;
diff --git a/markets/perps-market/contracts/modules/LiquidationModule.sol b/markets/perps-market/contracts/modules/LiquidationModule.sol
index 19a3a54e43..dba0ea3829 100644
--- a/markets/perps-market/contracts/modules/LiquidationModule.sol
+++ b/markets/perps-market/contracts/modules/LiquidationModule.sol
@@ -14,6 +14,10 @@ import {PerpsMarketConfiguration} from "../storage/PerpsMarketConfiguration.sol"
 import {GlobalPerpsMarket} from "../storage/GlobalPerpsMarket.sol";
 import {IMarketEvents} from "../interfaces/IMarketEvents.sol";
 
+/**
+ * @title Module for liquidating accounts.
+ * @dev See ILiquidationModule.
+ */
 contract LiquidationModule is ILiquidationModule, IMarketEvents {
     using DecimalMath for uint256;
     using SafeCastU256 for uint256;
@@ -24,6 +28,9 @@ contract LiquidationModule is ILiquidationModule, IMarketEvents {
     using PerpsMarketFactory for PerpsMarketFactory.Data;
     using GlobalPerpsMarketConfiguration for GlobalPerpsMarketConfiguration.Data;
 
+    /**
+     * @inheritdoc ILiquidationModule
+     */
     function liquidate(uint128 accountId) external override {
         SetUtil.UintSet storage liquidatableAccounts = GlobalPerpsMarket
             .load()
@@ -43,6 +50,9 @@ contract LiquidationModule is ILiquidationModule, IMarketEvents {
         }
     }
 
+    /**
+     * @inheritdoc ILiquidationModule
+     */
     function liquidateFlagged() external override {
         uint256[] memory liquidatableAccounts = GlobalPerpsMarket
             .load()
@@ -55,6 +65,9 @@ contract LiquidationModule is ILiquidationModule, IMarketEvents {
         }
     }
 
+    /**
+     * @dev liquidates an account
+     */
     function _liquidateAccount(PerpsAccount.Data storage account) internal {
         uint128 accountId = account.id;
         uint256[] memory openPositionMarketIds = account.openPositionMarketIds.values();
@@ -105,6 +118,9 @@ contract LiquidationModule is ILiquidationModule, IMarketEvents {
         emit AccountLiquidated(accountId, keeperLiquidationReward, accountFullyLiquidated);
     }
 
+    /**
+     * @dev process the accumulated liquidation rewards
+     */
     function _processLiquidationRewards(uint256 totalRewards) private returns (uint256 reward) {
         if (totalRewards == 0) {
             return 0;
diff --git a/markets/perps-market/contracts/modules/PerpsMarketFactoryModule.sol b/markets/perps-market/contracts/modules/PerpsMarketFactoryModule.sol
index 1a7011c0b3..bc0492a723 100644
--- a/markets/perps-market/contracts/modules/PerpsMarketFactoryModule.sol
+++ b/markets/perps-market/contracts/modules/PerpsMarketFactoryModule.sol
@@ -51,12 +51,18 @@ contract PerpsMarketFactoryModule is IPerpsMarketFactoryModule {
         store.oracle = synthetix.getOracleManager();
     }
 
+    /**
+     * @inheritdoc IPerpsMarketFactoryModule
+     */
     function setSpotMarket(ISpotMarketSystem spotMarket) external override {
         OwnableStorage.onlyOwner();
 
         PerpsMarketFactory.load().spotMarket = spotMarket;
     }
 
+    /**
+     * @inheritdoc IPerpsMarketFactoryModule
+     */
     function initializeFactory() external override returns (uint128) {
         FeatureFlag.ensureAccessToFeature(_CREATE_MARKET_FEATURE_FLAG);
         OwnableStorage.onlyOwner();
@@ -99,6 +105,9 @@ contract PerpsMarketFactoryModule is IPerpsMarketFactoryModule {
         return requestedMarketId;
     }
 
+    /**
+     * @inheritdoc IMarket
+     */
     // solc-ignore-next-line func-mutability
     function name(uint128 perpsMarketId) external view override returns (string memory) {
         // todo: set name on initialize?
@@ -106,6 +115,9 @@ contract PerpsMarketFactoryModule is IPerpsMarketFactoryModule {
         return "Perps Market";
     }
 
+    /**
+     * @inheritdoc IMarket
+     */
     function reportedDebt(uint128 perpsMarketId) external view override returns (uint256) {
         PerpsMarketFactory.Data storage factory = PerpsMarketFactory.load();
 
@@ -131,6 +143,9 @@ contract PerpsMarketFactoryModule is IPerpsMarketFactoryModule {
         return 0;
     }
 
+    /**
+     * @inheritdoc IMarket
+     */
     function minimumCredit(uint128 perpsMarketId) external view override returns (uint256) {
         PerpsMarketFactory.Data storage factory = PerpsMarketFactory.load();
 
diff --git a/markets/perps-market/contracts/modules/PerpsMarketModule.sol b/markets/perps-market/contracts/modules/PerpsMarketModule.sol
index c8d60b6636..58b7285b29 100644
--- a/markets/perps-market/contracts/modules/PerpsMarketModule.sol
+++ b/markets/perps-market/contracts/modules/PerpsMarketModule.sol
@@ -7,10 +7,17 @@ import {PerpsPrice} from "../storage/PerpsPrice.sol";
 import {AsyncOrder} from "../storage/AsyncOrder.sol";
 import {IPerpsMarketModule} from "../interfaces/IPerpsMarketModule.sol";
 
+/**
+ * @title Module for getting perps market information.
+ * @dev See IPerpsMarketModule.
+ */
 contract PerpsMarketModule is IPerpsMarketModule {
     using PerpsMarket for PerpsMarket.Data;
     using AsyncOrder for AsyncOrder.Data;
 
+    /**
+     * @inheritdoc IPerpsMarketModule
+     */
     function metadata(
         uint128 marketId
     ) external view override returns (string memory name, string memory symbol) {
@@ -18,30 +25,51 @@ contract PerpsMarketModule is IPerpsMarketModule {
         return (market.name, market.symbol);
     }
 
+    /**
+     * @inheritdoc IPerpsMarketModule
+     */
     function skew(uint128 marketId) external view override returns (int256) {
         return PerpsMarket.load(marketId).skew;
     }
 
+    /**
+     * @inheritdoc IPerpsMarketModule
+     */
     function size(uint128 marketId) external view override returns (uint256) {
         return PerpsMarket.load(marketId).size;
     }
 
+    /**
+     * @inheritdoc IPerpsMarketModule
+     */
     function maxOpenInterest(uint128 marketId) external view override returns (uint256) {
         return PerpsMarketConfiguration.load(marketId).maxMarketSize;
     }
 
+    /**
+     * @inheritdoc IPerpsMarketModule
+     */
     function currentFundingRate(uint128 marketId) external view override returns (int) {
         return PerpsMarket.load(marketId).currentFundingRate();
     }
 
+    /**
+     * @inheritdoc IPerpsMarketModule
+     */
     function currentFundingVelocity(uint128 marketId) external view override returns (int) {
         return PerpsMarket.load(marketId).currentFundingVelocity();
     }
 
+    /**
+     * @inheritdoc IPerpsMarketModule
+     */
     function indexPrice(uint128 marketId) external view override returns (uint) {
         return PerpsPrice.getCurrentPrice(marketId);
     }
 
+    /**
+     * @inheritdoc IPerpsMarketModule
+     */
     function fillPrice(
         uint128 marketId,
         int128 orderSize,
@@ -56,6 +84,9 @@ contract PerpsMarketModule is IPerpsMarketModule {
             );
     }
 
+    /**
+     * @inheritdoc IPerpsMarketModule
+     */
     function getMarketSummary(
         uint128 marketId
     ) external view override returns (MarketSummary memory summary) {
diff --git a/markets/perps-market/docs/index.md b/markets/perps-market/docs/index.md
index 8f1fdd6cc0..3cba695af6 100644
--- a/markets/perps-market/docs/index.md
+++ b/markets/perps-market/docs/index.md
@@ -30,7 +30,7 @@
 #### 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.
@@ -43,6 +43,24 @@
 
 **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
 
@@ -63,6 +81,22 @@
 * `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
@@ -347,24 +381,50 @@
   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
@@ -825,24 +885,49 @@
   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
@@ -887,12 +972,24 @@
   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
@@ -901,48 +998,107 @@
   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
@@ -951,3 +1107,9 @@
 
   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).
+