fixed natspec comment formatting (#90)

spot-contracts/contracts/BondIssuer.sol

@@ -7,7 +7,7 @@ import { IBondFactory } from "./_interfaces/buttonwood/IBondFactory.sol";
 import { IBondController } from "./_interfaces/buttonwood/IBondController.sol";
 import { IBondIssuer } from "./_interfaces/IBondIssuer.sol";
 
-/*
+/**
  *  @title BondIssuer
  *
  *  @notice An issuer periodically issues bonds based on a predefined configuration.
@@ -18,39 +18,39 @@ import { IBondIssuer } from "./_interfaces/IBondIssuer.sol";
 contract BondIssuer is IBondIssuer {
     using EnumerableSetUpgradeable for EnumerableSetUpgradeable.AddressSet;
 
-    // @notice Address of the bond factory.
+    /// @notice Address of the bond factory.
     IBondFactory public immutable bondFactory;
 
-    // @notice Time to elapse since last issue window start, after which a new bond can be issued.
-    //         AKA, issue frequency.
+    /// @notice Time to elapse since last issue window start, after which a new bond can be issued.
+    ///         AKA, issue frequency.
     uint256 public immutable minIssueTimeIntervalSec;
 
-    // @notice The issue window begins this many seconds into the minIssueTimeIntervalSec period.
-    // @dev For example if minIssueTimeIntervalSec is 604800 (1 week), and issueWindowOffsetSec is 93600
-    //      then the issue window opens at Friday 2AM GMT every week.
+    /// @notice The issue window begins this many seconds into the minIssueTimeIntervalSec period.
+    /// @dev For example if minIssueTimeIntervalSec is 604800 (1 week), and issueWindowOffsetSec is 93600
+    ///      then the issue window opens at Friday 2AM GMT every week.
     uint256 public immutable issueWindowOffsetSec;
 
-    // @notice The maximum maturity duration for the issued bonds.
-    // @dev In practice, bonds issued by this issuer won't have a constant duration as
-    //      block.timestamp when the issue function is invoked can vary.
-    //      Rather these bonds are designed to have a predictable maturity date.
+    /// @notice The maximum maturity duration for the issued bonds.
+    /// @dev In practice, bonds issued by this issuer won't have a constant duration as
+    ///      block.timestamp when the issue function is invoked can vary.
+    ///      Rather these bonds are designed to have a predictable maturity date.
     uint256 public immutable maxMaturityDuration;
 
-    // @notice The underlying rebasing token used for tranching.
+    /// @notice The underlying rebasing token used for tranching.
     address public immutable collateral;
 
-    // @notice The tranche ratios.
-    // @dev Each tranche ratio is expressed as a fixed point number
-    //      such that the sum of all the tranche ratios is exactly 1000.
-    //      https://github.com/buttonwood-protocol/tranche/blob/main/contracts/BondController.sol#L20
+    /// @notice The tranche ratios.
+    /// @dev Each tranche ratio is expressed as a fixed point number
+    ///      such that the sum of all the tranche ratios is exactly 1000.
+    ///      https://github.com/buttonwood-protocol/tranche/blob/main/contracts/BondController.sol#L20
     uint256[] public trancheRatios;
 
-    // @notice An enumerable list to keep track of bonds issued by this issuer.
-    // @dev Bonds are only added and never removed, thus the last item will always point
-    //      to the latest bond.
+    /// @notice An enumerable list to keep track of bonds issued by this issuer.
+    /// @dev Bonds are only added and never removed, thus the last item will always point
+    ///      to the latest bond.
     EnumerableSetUpgradeable.AddressSet private _issuedBonds;
 
-    // @notice The timestamp when the issue window opened during the last issue.
+    /// @notice The timestamp when the issue window opened during the last issue.
     uint256 public lastIssueWindowTimestamp;
 
     constructor(
@@ -96,7 +96,7 @@ contract BondIssuer is IBondIssuer {
     }
 
     /// @inheritdoc IBondIssuer
-    // @dev Lazily issues a new bond when the time is right.
+    /// @dev Lazily issues a new bond when the time is right.
     function getLatestBond() external override returns (IBondController) {
         issue();
         // NOTE: The latest bond will be at the end of the list.

spot-contracts/contracts/RouterV1.sol

@@ -11,7 +11,7 @@ import { ITranche } from "./_interfaces/buttonwood/ITranche.sol";
 import { IBondController } from "./_interfaces/buttonwood/IBondController.sol";
 import { IPerpetualTranche } from "./_interfaces/IPerpetualTranche.sol";
 
-/*
+/**
  *  @title RouterV1
  *
  *  @notice Contract to dry-run and batch multiple operations.
@@ -35,12 +35,12 @@ contract RouterV1 {
         _;
     }
 
-    // @notice Calculates the amount of tranche tokens minted after depositing into the deposit bond.
-    // @dev Used by off-chain services to preview a tranche operation.
-    // @param perp Address of the perp contract.
-    // @param collateralAmount The amount of collateral the user wants to tranche.
-    // @return bond The address of the current deposit bond.
-    // @return trancheAmts The tranche token amounts minted.
+    /// @notice Calculates the amount of tranche tokens minted after depositing into the deposit bond.
+    /// @dev Used by off-chain services to preview a tranche operation.
+    /// @param perp Address of the perp contract.
+    /// @param collateralAmount The amount of collateral the user wants to tranche.
+    /// @return bond The address of the current deposit bond.
+    /// @return trancheAmts The tranche token amounts minted.
     function previewTranche(IPerpetualTranche perp, uint256 collateralAmount)
         external
         afterPerpStateUpdate(perp)
@@ -59,14 +59,14 @@ contract RouterV1 {
         return (bond, td.tranches, trancheAmts);
     }
 
-    // @notice Calculates the amount of perp tokens minted and fees for the operation.
-    // @dev Used by off-chain services to preview a deposit operation.
-    // @param perp Address of the perp contract.
-    // @param trancheIn The address of the tranche token to be deposited.
-    // @param trancheInAmt The amount of tranche tokens deposited.
-    // @return mintAmt The amount of perp tokens minted.
-    // @return feeToken The address of the fee token.
-    // @return mintFee The fee charged for minting.
+    /// @notice Calculates the amount of perp tokens minted and fees for the operation.
+    /// @dev Used by off-chain services to preview a deposit operation.
+    /// @param perp Address of the perp contract.
+    /// @param trancheIn The address of the tranche token to be deposited.
+    /// @param trancheInAmt The amount of tranche tokens deposited.
+    /// @return mintAmt The amount of perp tokens minted.
+    /// @return feeToken The address of the fee token.
+    /// @return mintFee The fee charged for minting.
     function previewDeposit(
         IPerpetualTranche perp,
         ITranche trancheIn,
@@ -87,14 +87,14 @@ contract RouterV1 {
         return (mintAmt, feeToken, mintFee);
     }
 
-    // @notice Tranches the collateral using the current deposit bond and then deposits individual tranches
-    //         to mint perp tokens. It transfers the perp tokens back to the
-    //         transaction sender along with any unused tranches and fees.
-    // @param perp Address of the perp contract.
-    // @param bond Address of the deposit bond.
-    // @param collateralAmount The amount of collateral the user wants to tranche.
-    // @param feePaid The fee paid to the perp contract to mint perp.
-    // @dev Fee to be paid should be pre-computed off-chain using the preview function.
+    /// @notice Tranches the collateral using the current deposit bond and then deposits individual tranches
+    ///         to mint perp tokens. It transfers the perp tokens back to the
+    ///         transaction sender along with any unused tranches and fees.
+    /// @param perp Address of the perp contract.
+    /// @param bond Address of the deposit bond.
+    /// @param collateralAmount The amount of collateral the user wants to tranche.
+    /// @param feePaid The fee paid to the perp contract to mint perp.
+    /// @dev Fee to be paid should be pre-computed off-chain using the preview function.
     function trancheAndDeposit(
         IPerpetualTranche perp,
         IBondController bond,
@@ -151,15 +151,15 @@ contract RouterV1 {
         perp.safeTransfer(msg.sender, perp.balanceOf(address(this)));
     }
 
-    // @notice Calculates the reserve tokens that can be redeemed from the queue
-    //         for burning up to the requested amount of perp tokens.
-    // @dev Used by off-chain services to preview a redeem operation.
-    // @param perp Address of the perp contract.
-    // @param perpAmtBurnt The amount of perp tokens requested to be burnt.
-    // @return reserveTokens The list of reserve tokens redeemed.
-    // @return redemptionAmts The list of reserve token amounts redeemed.
-    // @return feeToken The address of the fee token.
-    // @return burnFee The fee charged for burning.
+    /// @notice Calculates the reserve tokens that can be redeemed from the queue
+    ///         for burning up to the requested amount of perp tokens.
+    /// @dev Used by off-chain services to preview a redeem operation.
+    /// @param perp Address of the perp contract.
+    /// @param perpAmtBurnt The amount of perp tokens requested to be burnt.
+    /// @return reserveTokens The list of reserve tokens redeemed.
+    /// @return redemptionAmts The list of reserve token amounts redeemed.
+    /// @return feeToken The address of the fee token.
+    /// @return burnFee The fee charged for burning.
     function previewRedeem(IPerpetualTranche perp, uint256 perpAmtBurnt)
         external
         afterPerpStateUpdate(perp)
@@ -179,18 +179,18 @@ contract RouterV1 {
         return (reserveTokens, redemptionAmts, feeToken, burnFee);
     }
 
-    // @notice Calculates the amount tranche tokens that can be rolled out, remainders and fees,
-    //         with a given tranche token rolled in and amount.
-    // @dev Used by off-chain services to preview a rollover operation.
-    // @param perp Address of the perp contract.
-    // @param trancheIn The tranche token deposited.
-    // @param tokenOut The reserve token requested to be withdrawn.
-    // @param trancheInAmt The amount of trancheIn tokens available to deposit.
-    // @param maxTokenOutAmtUsed The token balance to be used for rollover.
-    // @dev Set maxTokenOutAmtUsed to max(uint256) to use the entire balance.
-    // @return r The amounts rolled over and remaining.
-    // @return feeToken The address of the fee token.
-    // @return rolloverFee The fee paid by the caller.
+    /// @notice Calculates the amount tranche tokens that can be rolled out, remainders and fees,
+    ///         with a given tranche token rolled in and amount.
+    /// @dev Used by off-chain services to preview a rollover operation.
+    /// @param perp Address of the perp contract.
+    /// @param trancheIn The tranche token deposited.
+    /// @param tokenOut The reserve token requested to be withdrawn.
+    /// @param trancheInAmtRequested The amount of trancheIn tokens available to deposit.
+    /// @param maxTokenOutAmtUsed The token balance to be used for rollover.
+    /// @dev Set maxTokenOutAmtUsed to max(uint256) to use the entire balance.
+    /// @return r The amounts rolled over and remaining.
+    /// @return feeToken The address of the fee token.
+    /// @return rolloverFee The fee paid by the caller.
     function previewRollover(
         IPerpetualTranche perp,
         ITranche trancheIn,
@@ -226,12 +226,12 @@ contract RouterV1 {
         uint256 trancheInAmt;
     }
 
-    // @notice Tranches collateral and performs a batch rollover.
-    // @param perp Address of the perp contract.
-    // @param bond Address of the deposit bond.
-    // @param collateralAmount The amount of collateral the user wants to tranche.
-    // @param rollovers List of batch rollover operations pre-computed off-chain.
-    // @param feePaid The fee paid by the user performing rollover (fee could be negative).
+    /// @notice Tranches collateral and performs a batch rollover.
+    /// @param perp Address of the perp contract.
+    /// @param bond Address of the deposit bond.
+    /// @param collateralAmount The amount of collateral the user wants to tranche.
+    /// @param rollovers List of batch rollover operations pre-computed off-chain.
+    /// @param feePaid The fee paid by the user performing rollover (fee could be negative).
     function trancheAndRollover(
         IPerpetualTranche perp,
         IBondController bond,
@@ -297,7 +297,7 @@ contract RouterV1 {
         }
     }
 
-    // @dev Checks if the spender has sufficient allowance. If not, approves the maximum possible amount.
+    /// @dev Checks if the spender has sufficient allowance. If not, approves the maximum possible amount.
     function _checkAndApproveMax(
         IERC20Upgradeable token,
         address spender,

spot-contracts/contracts/_interfaces/IBondIssuer.sol

@@ -12,23 +12,23 @@ interface IBondIssuer {
     /// @return Address of the collateral token.
     function collateral() external view returns (address);
 
-    // @notice Issues a new bond if sufficient time has elapsed since the last issue.
+    /// @notice Issues a new bond if sufficient time has elapsed since the last issue.
     function issue() external;
 
-    // @notice Checks if a given bond has been issued by the issuer.
-    // @param Address of the bond to check.
-    // @return if the bond has been issued by the issuer.
+    /// @notice Checks if a given bond has been issued by the issuer.
+    /// @param bond Address of the bond to check.
+    /// @return if the bond has been issued by the issuer.
     function isInstance(IBondController bond) external view returns (bool);
 
-    // @notice Fetches the most recently issued bond.
-    // @return Address of the most recent bond.
+    /// @notice Fetches the most recently issued bond.
+    /// @return Address of the most recent bond.
     function getLatestBond() external returns (IBondController);
 
-    // @notice Returns the total number of bonds issued by this issuer.
-    // @return Number of bonds.
+    /// @notice Returns the total number of bonds issued by this issuer.
+    /// @return Number of bonds.
     function issuedCount() external view returns (uint256);
 
-    // @notice The bond address from the issued list by index.
-    // @return Address of the bond.
+    /// @notice The bond address from the issued list by index.
+    /// @return Address of the bond.
     function issuedBondAt(uint256 index) external view returns (IBondController);
 }

spot-contracts/contracts/_interfaces/IDiscountStrategy.sol

@@ -4,11 +4,11 @@ pragma solidity ^0.8.0;
 import { IERC20Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/IERC20Upgradeable.sol";
 
 interface IDiscountStrategy {
-    // @notice Computes the discount to be applied to a given tranche token.
-    // @param tranche The tranche token to compute discount for.
-    // @return The discount as a fixed point number with `decimals()`.
+    /// @notice Computes the discount to be applied to a given tranche token.
+    /// @param tranche The tranche token to compute discount for.
+    /// @return The discount as a fixed point number with `decimals()`.
     function computeTrancheDiscount(IERC20Upgradeable tranche) external view returns (uint256);
 
-    // @notice Number of discount decimals.
+    /// @notice Number of discount decimals.
     function decimals() external view returns (uint8);
 }

spot-contracts/contracts/_interfaces/IFeeStrategy.sol

@@ -4,36 +4,36 @@ pragma solidity ^0.8.0;
 import { IERC20Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/IERC20Upgradeable.sol";
 
 interface IFeeStrategy {
-    // @notice Address of the fee token.
+    /// @notice Address of the fee token.
     function feeToken() external view returns (IERC20Upgradeable);
 
-    // @notice Computes the fees while minting given amount of perp tokens.
-    // @dev The mint fee can be either positive or negative. When positive it's paid by the minting users to the reserve.
-    //      When negative its paid to the minting users by the reserve.
-    //      The protocol fee is always non-negative and is paid by the users minting to the
-    //      perp contract's fee collector.
-    // @param amount The amount of perp tokens to be minted.
-    // @return reserveFee The fee paid to the reserve to mint perp tokens.
-    // @return protocolFee The fee paid to the protocol to mint perp tokens.
+    /// @notice Computes the fees while minting given amount of perp tokens.
+    /// @dev The mint fee can be either positive or negative. When positive it's paid by the minting users to the reserve.
+    ///      When negative its paid to the minting users by the reserve.
+    ///      The protocol fee is always non-negative and is paid by the users minting to the
+    ///      perp contract's fee collector.
+    /// @param amount The amount of perp tokens to be minted.
+    /// @return reserveFee The fee paid to the reserve to mint perp tokens.
+    /// @return protocolFee The fee paid to the protocol to mint perp tokens.
     function computeMintFees(uint256 amount) external view returns (int256 reserveFee, uint256 protocolFee);
 
-    // @notice Computes the fees while burning given amount of perp tokens.
-    // @dev The burn fee can be either positive or negative. When positive it's paid by the burning users to the reserve.
-    //      When negative its paid to the burning users by the reserve.
-    //      The protocol fee is always non-negative and is paid by the users burning to the
-    //      perp contract's fee collector.
-    // @param amount The amount of perp tokens to be burnt.
-    // @return reserveFee The fee paid to the reserve to burn perp tokens.
-    // @return protocolFee The fee paid to the protocol to burn perp tokens.
+    /// @notice Computes the fees while burning given amount of perp tokens.
+    /// @dev The burn fee can be either positive or negative. When positive it's paid by the burning users to the reserve.
+    ///      When negative its paid to the burning users by the reserve.
+    ///      The protocol fee is always non-negative and is paid by the users burning to the
+    ///      perp contract's fee collector.
+    /// @param amount The amount of perp tokens to be burnt.
+    /// @return reserveFee The fee paid to the reserve to burn perp tokens.
+    /// @return protocolFee The fee paid to the protocol to burn perp tokens.
     function computeBurnFees(uint256 amount) external view returns (int256 reserveFee, uint256 protocolFee);
 
-    // @notice Computes the fees while rolling over given amount of perp tokens.
-    // @dev The rollover fee can be either positive or negative. When positive it's paid by the users rolling over to the reserve.
-    //      When negative its paid to the users rolling over by the reserve.
-    //      The protocol fee is always positive and is paid by the users rolling over to the
-    //      perp contract's fee collector.
-    // @param amount The Perp-denominated value of the tranches being rolled over.
-    // @return reserveFee The fee paid to the reserve to rollover tokens.
-    // @return protocolFee The fee paid to the protocol to rollover tokens.
+    /// @notice Computes the fees while rolling over given amount of perp tokens.
+    /// @dev The rollover fee can be either positive or negative. When positive it's paid by the users rolling over to the reserve.
+    ///      When negative its paid to the users rolling over by the reserve.
+    ///      The protocol fee is always positive and is paid by the users rolling over to the
+    ///      perp contract's fee collector.
+    /// @param amount The Perp-denominated value of the tranches being rolled over.
+    /// @return reserveFee The fee paid to the reserve to rollover tokens.
+    /// @return protocolFee The fee paid to the protocol to rollover tokens.
     function computeRolloverFees(uint256 amount) external view returns (int256 reserveFee, uint256 protocolFee);
 }