8

Is there specific way to explain the variables of a struct using the Natspec format? I do something like:

struct XYZ{
   uint x; //Explain what it does
   uint y;
}

Is it this the right way for structs, or like functions do we have to define the comment at the top?

3
  • Like functions....... Jun 14, 2020 at 12:05
  • 3
    Looks like Compound is using @member to annotate struct fields, even if this is not a standard pattern (it's not found in the NatSpec documentation). Mar 6, 2021 at 14:33
  • 1
    Update: it looks like Solidity supports the @custom directive now, which can be used for application-specific semantics Sep 5, 2022 at 8:03

1 Answer 1

0

How AAVE did it seems a bit inconsistent although, the code is understandable IMO.

library DataTypes {
  // refer to the whitepaper, section 1.1 basic concepts for a formal description of these properties.
  struct ReserveData {
    //stores the reserve configuration
    ReserveConfigurationMap configuration;
    //the liquidity index. Expressed in ray
    uint128 liquidityIndex;
    //variable borrow index. Expressed in ray
    uint128 variableBorrowIndex;
    //the current supply rate. Expressed in ray
    uint128 currentLiquidityRate;
    //the current variable borrow rate. Expressed in ray
    uint128 currentVariableBorrowRate;
    //the current stable borrow rate. Expressed in ray
    uint128 currentStableBorrowRate;
    uint40 lastUpdateTimestamp;
    //tokens addresses
    address aTokenAddress;
    address stableDebtTokenAddress;
    address variableDebtTokenAddress;
    //address of the interest rate strategy
    address interestRateStrategyAddress;
    //the id of the reserve. Represents the position in the list of the active reserves
    uint8 id;
  }

https://github.com/aave/aave-v3-core/blob/master/contracts/protocol/libraries/types/DataTypes.sol

They have 9 audits from some really big companies in the game with over a billion dollars within their protocol, so I would imagine they're doing something right


UniSwap-v3 also used a similar pattern:


    struct Slot0 {
        // the current price
        uint160 sqrtPriceX96;
        // the current tick
        int24 tick;
        // the most-recently updated index of the observations array
        uint16 observationIndex;
        // the current maximum number of observations that are being stored
        uint16 observationCardinality;
        // the next maximum number of observations to store, triggered in observations.write
        uint16 observationCardinalityNext;
        // the current protocol fee as a percentage of the swap fee taken on withdrawal
        // represented as an integer denominator (1/x)%
        uint8 feeProtocol;
        // whether the pool is locked
        bool unlocked;
    }

https://github.com/Uniswap/v3-core/blob/main/contracts/UniswapV3Pool.sol


Openzeppelin seems to follow a similar pattern as well:

struct Set {
        // Storage of set values
        bytes32[] _values;
        // Position of the value in the `values` array, plus 1 because index 0
        // means a value is not in the set.
        mapping(bytes32 => uint256) _indexes;
    }

https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/utils/structs/EnumerableSet.sol

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.