From 5c060d67aa0f6b8ffd5cc144c5dce6393a978a43 Mon Sep 17 00:00:00 2001
From: JordyRo1 <jordy.romu@orange.fr>
Date: Sat, 2 Nov 2024 21:49:20 +0100
Subject: [PATCH] feat: DataParser.sol documentation

---
 solidity/src/libraries/DataParser.sol | 45 ++++++++++++++++++++++++++-
 1 file changed, 44 insertions(+), 1 deletion(-)

diff --git a/solidity/src/libraries/DataParser.sol b/solidity/src/libraries/DataParser.sol
index 691c5842..5363ce7f 100644
--- a/solidity/src/libraries/DataParser.sol
+++ b/solidity/src/libraries/DataParser.sol
@@ -5,16 +5,35 @@ import "./BytesLib.sol";
 import "../interfaces/PragmaStructs.sol";
 import "./ErrorsLib.sol";
 
+
+/// @title DataParser Library
+/// @notice A library for parsing various data feed types into structured data.
+/// @dev This library uses `BytesLib` for handling byte data, and assumes that data is encoded in a specific format.
+/// The calldata format can be found on https://docs.pragmaoracle.com/
+/// @custom:security-contact security@pragma.build
 library DataParser {
     using BytesLib for bytes;
 
+
+    /// @notice Parses the raw byte data and returns a structured `ParsedData` type.
+    /// @dev Determines the feed type based on the data and parses accordingly.
+    /// Reverts if the data feed type is invalid.
+    /// @param data The raw byte-encoded data to parse.
+    /// @return ParsedData struct containing the parsed data.
     function parse(bytes memory data) internal pure returns (ParsedData memory) {
-        uint8 offset = 2; // type of feed after the asset class
 
+        // Each update data has a feedId as first 31-bytes (and stored as 32-bytes). The two first bytes are allocated to the asset class.
+        // The two next bytes are respectively for the feed type and the feed type variant. Finally the remaining 27 bytes are allocated to the 
+        // pair id. In order to retrieve the feed type, we need to skip the first 2 bytes. 
+        uint8 offset = 2; // skips the asset class.
+
+        // Extract the feed type
         uint8 rawDataType = data.toUint8(offset);
         FeedType dataType = safeCastToFeedType(rawDataType);
         ParsedData memory parsedData = StructsInitializers.initializeParsedData();
         parsedData.dataType = dataType;
+
+        // Fill the storage  based on the feed type
         if (dataType == FeedType.SpotMedian) {
             parsedData.spot = parseSpotData(data);
         } else if (dataType == FeedType.Twap) {
@@ -32,6 +51,10 @@ library DataParser {
         return parsedData;
     }
 
+    /// @notice Safely casts a raw data type value to `FeedType`.
+    /// @dev Reverts if the raw data type exceeds the maximum value of `FeedType`.
+    /// @param rawDataType The raw data type byte.
+    /// @return FeedType The casted `FeedType`.
     function safeCastToFeedType(uint8 rawDataType) internal pure returns (FeedType) {
         if (rawDataType <= uint8(type(FeedType).max)) {
             return FeedType(rawDataType);
@@ -40,6 +63,11 @@ library DataParser {
         }
     }
 
+    /// @notice Parses metadata information from the byte data starting at a given index.
+    /// @param data The raw byte-encoded data.
+    /// @param startIndex The starting index for metadata parsing.
+    /// @return metadata The parsed `Metadata` structure.
+    /// @return index The updated index after parsing metadata.
     function parseMetadata(bytes memory data, uint256 startIndex) internal pure returns (Metadata memory, uint256) {
         Metadata memory metadata = StructsInitializers.initializeMetadata();
         uint256 index = startIndex;
@@ -59,6 +87,9 @@ library DataParser {
         return (metadata, index);
     }
 
+    /// @notice Parses SpotMedian data from the byte data.
+    /// @param data The raw byte-encoded data.
+    /// @return SpotMedian A `SpotMedian` struct with parsed data.
     function parseSpotData(bytes memory data) internal pure returns (SpotMedian memory) {
         SpotMedian memory entry = StructsInitializers.initializeSpotMedian();
         uint256 index = 0;
@@ -74,6 +105,9 @@ library DataParser {
         return entry;
     }
 
+    /// @notice Parses TWAP (Time-Weighted Average Price) data from the byte data.
+    /// @param data The raw byte-encoded data.
+    /// @return TWAP A `TWAP` struct with parsed data.
     function parseTWAPData(bytes memory data) internal pure returns (TWAP memory) {
         TWAP memory entry = StructsInitializers.initializeTwap();
         uint256 index = 0;
@@ -100,6 +134,9 @@ library DataParser {
         return entry;
     }
 
+    /// @notice Parses realized volatility data from the byte data.
+    /// @param data The raw byte-encoded data.
+    /// @return RealizedVolatility A `RealizedVolatility` struct with parsed data.
     function parseRealizedVolatilityData(bytes memory data) internal pure returns (RealizedVolatility memory) {
         RealizedVolatility memory entry = StructsInitializers.initializeRV();
         uint256 index = 0;
@@ -129,6 +166,9 @@ library DataParser {
         return entry;
     }
 
+    /// @notice Parses options data from the byte data.
+    /// @param data The raw byte-encoded data.
+    /// @return Options An `Options` struct with parsed data.
     function parseOptionsData(bytes memory data) internal pure returns (Options memory) {
         Options memory entry = StructsInitializers.initializeOptions();
         uint256 index = 0;
@@ -170,6 +210,9 @@ library DataParser {
         return entry;
     }
 
+    /// @notice Parses perpetuals data from the byte data.
+    /// @param data The raw byte-encoded data.
+    /// @return Perp A `Perp` struct with parsed data.
     function parsePerpData(bytes memory data) internal pure returns (Perp memory) {
         Perp memory entry = StructsInitializers.initializePerpetuals();
         uint256 index = 0;