docs: update NatSpec comments

src/ReservoirPair.sol

@@ -135,11 +135,10 @@ abstract contract ReservoirPair is IAssetManagedPair, ReservoirERC20 {
         _writeSlot0Timestamp(sSlot0, aBlockTimestampLast, false);
     }
 
-    /// @notice update reserves with new balances
-    /// @notice on the first call per block, accumulate price oracle using previous instant prices and write the new instant prices
-    /// @dev we write an oracle sample even at the time of pair creation. Also we do not update instant prices for
-    /// subsequent mint/burn/swaps in the same block. the team has assessed that this is a small risk given the very
-    /// fast block times on L2s and has decided to make the tradeoff to minimize complexity
+    /// @notice Updates reserves with new balances.
+    /// @notice On the first call per block, accumulate price oracle using previous instant prices and write the new instant prices.
+    /// @dev We write an oracle sample even at the time of pair creation. The price is not updated on subsequent swaps as manipulating
+    /// the instantaneous price does not materially affect the TWAP, especially when using clamped pricing.
     function _updateAndUnlock(
         Slot0 storage sSlot0,
         uint256 aBalance0,
@@ -585,10 +584,10 @@ abstract contract ReservoirPair is IAssetManagedPair, ReservoirERC20 {
         }
     }
 
-    /// @param aBalance0 in its native precision
-    /// @param aBalance1 in its native precision
-    /// @return spotPrice where 1e18 == 1
-    /// @return logSpotPrice natural log (ln) of the spotPrice
+    /// @param aBalance0 The balance of token0 in its native precision.
+    /// @param aBalance1 The balance of token1 in its native precision.
+    /// @return spotPrice Expressed as 1e18 == 1.
+    /// @return logSpotPrice The natural log (ln) of the spotPrice.
     function _calcSpotAndLogPrice(uint256 aBalance0, uint256 aBalance1)
         internal
         virtual

src/curve/stable/StableMintBurn.sol

@@ -63,7 +63,7 @@ contract StableMintBurn is StablePair {
         require(rToken0Fee <= type(uint104).max && rToken1Fee <= type(uint104).max, "SP: NON_OPTIMAL_FEE_TOO_LARGE");
     }
 
-    /// @notice Get D, the StableSwap invariant, based on a set of balances and a particular A.
+    /// @notice Calculates D, the StableSwap invariant, based on a set of balances and a particular A.
     /// See the StableSwap paper for details.
     /// @dev Originally
     /// https://github.com/saddle-finance/saddle-contract/blob/0b76f7fb519e34b878aa1d58cffc8d8dc0572c12/contracts/SwapUtils.sol#L319.

src/libraries/ConstantProductOracleMath.sol

@@ -23,10 +23,10 @@ library ConstantProductOracleMath {
 
     /**
      * @notice Calculates the spot price of token1/token0 for the constant product pair.
-     * @param reserve0 normalized to 18 decimals, and should never be 0 as checked by _updateAndUnlock().
-     * @param reserve1 normalized to 18 decimals, and should never be 0 as checked by _updateAndUnlock().
-     * @return spotPrice price of token1/token0, 18 decimals fixed point number. Minimum price is 1e-18 (1 wei), as we do not round to zero.
-     * @return logSpotPrice natural log of the spot price, 4 decimal fixed point number. Min value is 1
+     * @param reserve0 The reserve of token0 normalized to 18 decimals, and should never be 0 as checked by _updateAndUnlock().
+     * @param reserve1 The reserve of token1 normalized to 18 decimals, and should never be 0 as checked by _updateAndUnlock().
+     * @return spotPrice The price of token1/token0, expressed as a 18 decimals fixed point number. The minimum price is 1e-18 (1 wei), as we do not round to zero.
+     * @return logSpotPrice The natural log of the spot price, 4 decimal fixed point number. Min value is 1.
      */
     function calcLogPrice(uint256 reserve0, uint256 reserve1)
         internal

src/libraries/StableOracleMath.sol

@@ -10,12 +10,12 @@ import { StableMath } from "src/libraries/StableMath.sol";
 library StableOracleMath {
     using FixedPointMathLib for uint256;
 
-    /// @notice Calculates the spot price of token1/token0 for the stable pair
-    /// @param amplificationParameter in precise form (see StableMath.A_PRECISION)
-    /// @param reserve0 normalized to 18 decimals, and should never be 0 as checked by _updateAndUnlock()
-    /// @param reserve1 normalized to 18 decimals, and should never be 0 as checked by _updateAndUnlock()
-    /// @return spotPrice price of token1/token0, 18 decimal fixed point number
-    /// @return logSpotPrice natural log of the spot price, 4 decimal fixed point number
+    /// @notice Calculates the spot price of token1/token0 for the stable pair.
+    /// @param amplificationParameter The stable amplification parameter in precise form (see StableMath.A_PRECISION).
+    /// @param reserve0 The reserve of token0 normalized to 18 decimals, and should never be 0 as checked by _updateAndUnlock().
+    /// @param reserve1 The reserve of token1 normalized to 18 decimals, and should never be 0 as checked by _updateAndUnlock().
+    /// @return spotPrice The price of token1/token0, a 18 decimal fixed point number.
+    /// @return logSpotPrice The natural log of the spot price, a 4 decimal fixed point number.
     function calcLogPrice(uint256 amplificationParameter, uint256 reserve0, uint256 reserve1)
         internal
         pure
@@ -26,11 +26,11 @@ library StableOracleMath {
         logSpotPrice = LogCompression.toLowResLog(spotPrice);
     }
 
-    /// @notice Calculates the spot price of token1 in token0
-    /// @param amplificationParameter in precise form (see StableMath.A_PRECISION)
-    /// @param reserve0 normalized to 18 decimals
-    /// @param reserve1 normalized to 18 decimals
-    /// @return spotPrice 18 decimal fixed point number. Minimum price is 1e-18 (1 wei)
+    /// @notice Calculates the spot price of token1 in token0.
+    /// @param amplificationParameter The stable amplification parameter in precise form (see StableMath.A_PRECISION).
+    /// @param reserve0 The reserve of token0 normalized to 18 decimals.
+    /// @param reserve1 The reserve of token1 normalized to 18 decimals.
+    /// @return spotPrice The price expressed as a 18 decimal fixed point number. Minimum price is 1e-18 (1 wei).
     function calcSpotPrice(uint256 amplificationParameter, uint256 reserve0, uint256 reserve1)
         internal
         pure