docs(store): add NatSpec to Store utils (#1648)

Co-authored-by: alvarius <[email protected]>

packages/store/src/constants.sol

@@ -1,25 +1,43 @@
 // SPDX-License-Identifier: MIT
 pragma solidity >=0.8.21;
 
+/**
+ * @title Shared Constants for EVM and Schema Handling
+ * @dev This file provides constants for better handling of EVM and Schema related functionalities.
+ */
+
 /* Shared constants */
 
-// Total byte length of an EVM word
+/// @dev Represents the total byte length of an EVM word.
 uint256 constant WORD_SIZE = 32;
-// Index of the last byte in an EVM word
+
+/// @dev Represents the index of the last byte in an EVM word.
 uint256 constant WORD_LAST_INDEX = 31;
-// Conversion for bit shifting
+
+/// @dev Represents the conversion constant from byte to bits.
 uint256 constant BYTE_TO_BITS = 8;
 
-// Schema's capacity
+/// @dev Represents the maximum number of fields a Schema can handle.
 uint256 constant MAX_TOTAL_FIELDS = 28;
-// FieldLayout's capacity
+
+/// @dev Represents the maximum number of static fields in a FieldLayout.
 uint256 constant MAX_STATIC_FIELDS = 28;
-// PackedCounter's capacity
+
+/// @dev Represents the maximum number of dynamic fields that can be packed in a PackedCounter.
 uint256 constant MAX_DYNAMIC_FIELDS = 5;
 
-// FieldLayout and Schema have the same offsets for metadata
+/**
+ * @title LayoutOffsets Library
+ * @notice This library provides constant offsets for FieldLayout and Schema metadata.
+ * @dev FieldLayout and Schema utilize the same offset values for metadata.
+ */
 library LayoutOffsets {
+  /// @notice Represents the total length offset within the EVM word.
   uint256 internal constant TOTAL_LENGTH = (WORD_SIZE - 2) * BYTE_TO_BITS;
+
+  /// @notice Represents the number of static fields offset within the EVM word.
   uint256 internal constant NUM_STATIC_FIELDS = (WORD_SIZE - 2 - 1) * BYTE_TO_BITS;
+
+  /// @notice Represents the number of dynamic fields offset within the EVM word.
   uint256 internal constant NUM_DYNAMIC_FIELDS = (WORD_SIZE - 2 - 1 - 1) * BYTE_TO_BITS;
 }

packages/store/src/leftMask.sol

@@ -2,19 +2,27 @@
 pragma solidity >=0.8.21;
 
 /**
- * Adapted from https://github.com/dk1a/solidity-stringutils/blob/main/src/utils/mem.sol#L149-L167
- * @dev Left-aligned byte mask (e.g. for partial mload/mstore).
- * For byteLength >= 32 returns type(uint256).max
- *
- * length 0:   0x000000...000000
- * length 1:   0xff0000...000000
- * length 2:   0xffff00...000000
- * ...
- * length 30:  0xffffff...ff0000
- * length 31:  0xffffff...ffff00
- * length 32+: 0xffffff...ffffff
+ * @title Byte Mask Utility
+ * @notice Utility functions to manage bytes in memory.
+ * @dev Adapted from https://github.com/dk1a/solidity-stringutils/blob/main/src/utils/mem.sol#L149-L167
  */
-function leftMask(uint256 byteLength) pure returns (uint256) {
+
+/**
+ * @notice Computes a left-aligned byte mask based on the provided byte length.
+ * @dev The mask is used to extract a specified number of leftmost bytes.
+ *      For byte lengths greater than or equal to 32, it returns the max value of type(uint256).
+ *      Examples:
+ *          length 0:   0x000000...000000
+ *          length 1:   0xff0000...000000
+ *          length 2:   0xffff00...000000
+ *          ...
+ *          length 30:  0xffffff...ff0000
+ *          length 31:  0xffffff...ffff00
+ *          length 32+: 0xffffff...ffffff
+ * @param byteLength The number of leftmost bytes to be masked.
+ * @return mask A left-aligned byte mask corresponding to the specified byte length.
+ */
+function leftMask(uint256 byteLength) pure returns (uint256 mask) {
   unchecked {
     return ~(type(uint256).max >> (byteLength * 8));
   }

packages/store/src/storeHookTypes.sol

@@ -1,15 +1,37 @@
 // SPDX-License-Identifier: MIT
 pragma solidity >=0.8.21;
 
+/**
+ * @title Store Hook Flags
+ * @notice Constants for enabling store hooks.
+ * @dev These bitmaps can be used to enable selected store hooks. They can be combined with a bitwise OR (`|`).
+ */
+
+/// @dev Flag to enable the `onBeforeSetRecord` hook.
 uint8 constant BEFORE_SET_RECORD = 1 << 0;
+
+/// @dev Flag to enable the `afterSetRecord` hook.
 uint8 constant AFTER_SET_RECORD = 1 << 1;
+
+/// @dev Flag to enable the `beforeSpliceStaticData` hook.
 uint8 constant BEFORE_SPLICE_STATIC_DATA = 1 << 2;
+
+/// @dev Flag to enable the `afterSpliceStaticData` hook.
 uint8 constant AFTER_SPLICE_STATIC_DATA = 1 << 3;
+
+/// @dev Flag to enable the `beforeSpliceDynamicData` hook.
 uint8 constant BEFORE_SPLICE_DYNAMIC_DATA = 1 << 4;
+
+/// @dev Flag to enable the `afterSpliceDynamicData` hook.
 uint8 constant AFTER_SPLICE_DYNAMIC_DATA = 1 << 5;
+
+/// @dev Flag to enable the `beforeDeleteRecord` hook.
 uint8 constant BEFORE_DELETE_RECORD = 1 << 6;
+
+/// @dev Flag to enable the `afterDeleteRecord` hook.
 uint8 constant AFTER_DELETE_RECORD = 1 << 7;
 
+/// @dev Bitmap to enable all hooks.
 uint8 constant ALL = BEFORE_SET_RECORD |
   AFTER_SET_RECORD |
   BEFORE_SPLICE_STATIC_DATA |
@@ -19,11 +41,13 @@ uint8 constant ALL = BEFORE_SET_RECORD |
   BEFORE_DELETE_RECORD |
   AFTER_DELETE_RECORD;
 
+/// @dev Bitmap to enable all "before" hooks.
 uint8 constant BEFORE_ALL = BEFORE_SET_RECORD |
   BEFORE_SPLICE_STATIC_DATA |
   BEFORE_SPLICE_DYNAMIC_DATA |
   BEFORE_DELETE_RECORD;
 
+/// @dev Bitmap to enable all "after" hooks.
 uint8 constant AFTER_ALL = AFTER_SET_RECORD |
   AFTER_SPLICE_STATIC_DATA |
   AFTER_SPLICE_DYNAMIC_DATA |

packages/store/src/storeResourceTypes.sol

@@ -1,5 +1,14 @@
 // SPDX-License-Identifier: MIT
 pragma solidity >=0.8.21;
 
+/**
+ * @title Resource Identifiers
+ * @notice Constants representing unique identifiers for different resource types.
+ * @dev These identifiers can be used to distinguish between various resource types.
+ */
+
+/// @dev Identifier for a resource table.
 bytes2 constant RESOURCE_TABLE = "tb";
+
+/// @dev Identifier for an offchain resource table.
 bytes2 constant RESOURCE_OFFCHAIN_TABLE = "ot";

packages/store/src/version.sol

@@ -1,4 +1,10 @@
 // SPDX-License-Identifier: MIT
 pragma solidity >=0.8.21;
 
+/**
+ * @title Store Versioning
+ * @notice Contains a constant representing the version of the store.
+ */
+
+/// @dev Identifier for the current store version.
 bytes32 constant STORE_VERSION = "1.0.0-unaudited";