feat: natspec

Signed-off-by: Pablo Maldonado <pablo@umaproject.org>

src/oracles/CoinbaseOracle.sol

@@ -3,6 +3,10 @@ pragma solidity 0.8.17;
 
 import {IAggregatorV3Source} from "../interfaces/chainlink/IAggregatorV3Source.sol";
 
+/**
+ * @title CoinbaseOracle
+ * @notice A smart contract that serves as an oracle for price data reported by a designated reporter.
+ */
 contract CoinbaseOracle is IAggregatorV3Source {
     address immutable reporter;
 
@@ -15,12 +19,34 @@ contract CoinbaseOracle is IAggregatorV3Source {
     mapping(uint80 => int256) public roundAnswers;
     mapping(uint80 => uint256) public roundTimestamps;
 
+    /**
+     * @notice Emitted when a new price is pushed.
+     * @param roundId The round ID of the new price.
+     * @param price The price that was pushed.
+     * @param timestamp The timestamp at which the price was pushed.
+     */
+    event PricePushed(uint80 indexed roundId, int256 price, uint256 timestamp);
+
+    /**
+     * @notice Constructor to initialize the CoinbaseOracle contract.
+     * @param _symbol The symbol of the asset being reported.
+     * @param _decimals The number of decimals in the reported price.
+     * @param _reporter The address of the reporter allowed to push price data.
+     */
     constructor(string memory _symbol, uint8 _decimals, address _reporter) {
         symbol = _symbol;
         decimals = _decimals;
         reporter = _reporter;
     }
 
+    /**
+     * @notice Returns the latest round data.
+     * @return roundId The ID of the latest round.
+     * @return answer The latest price.
+     * @return startedAt The timestamp when the round started.
+     * @return updatedAt The timestamp when the round was updated.
+     * @return answeredInRound The round ID in which the answer was computed.
+     */
     function latestRoundData()
         external
         view
@@ -32,6 +58,15 @@ contract CoinbaseOracle is IAggregatorV3Source {
         return (lastRoundId, latestAnswer, latestTimestamp, latestTimestamp, lastRoundId);
     }
 
+    /**
+     * @notice Returns the data for a specific round.
+     * @param _roundId The round ID to retrieve the data for.
+     * @return roundId The ID of the round.
+     * @return answer The price of the round.
+     * @return startedAt The timestamp when the round started.
+     * @return updatedAt The timestamp when the round was updated.
+     * @return answeredInRound The round ID in which the answer was computed.
+     */
     function getRoundData(uint80 _roundId)
         external
         view
@@ -43,6 +78,11 @@ contract CoinbaseOracle is IAggregatorV3Source {
         return (_roundId, latestAnswer, latestTimestamp, latestTimestamp, _roundId);
     }
 
+    /**
+     * @notice Pushes a new price to the oracle.
+     * @param priceData The encoded price data.
+     * @param signature The signature to verify the authenticity of the data.
+     */
     function pushPrice(bytes memory priceData, bytes memory signature) external {
         (
             string memory kind, // e.g. "price"
@@ -62,9 +102,16 @@ contract CoinbaseOracle is IAggregatorV3Source {
         lastRoundId++;
         roundAnswers[lastRoundId] = int256(price);
         roundTimestamps[lastRoundId] = timestamp;
+
+        emit PricePushed(lastRoundId, int256(price), timestamp);
     }
 
-    // Internal function to recover the signer of a message
+    /**
+     * @notice Internal function to recover the signer of a message.
+     * @param message The message that was signed.
+     * @param signature The signature to recover the signer from.
+     * @return The address of the signer.
+     */
     function recoverSigner(bytes memory message, bytes memory signature) internal pure returns (address) {
         (bytes32 r, bytes32 s, uint8 v) = abi.decode(signature, (bytes32, bytes32, uint8));
         bytes32 hash = keccak256(abi.encodePacked("\x19Ethereum Signed Message:\n32", keccak256(message)));