doc: improve readme

Author: tejasbadadare

target_chains/ethereum/pulse_sdk/solidity/README.md

@@ -56,15 +56,28 @@ struct SubscriptionParams {
 }
 ```
 
+### SubscriptionStatus
+
+This struct tracks the current status of a Pulse subscription:
+
+```solidity
+struct SubscriptionStatus {
+  uint256 priceLastUpdatedAt; // Timestamp of the last update. All feeds in the subscription are updated together.
+  uint256 balanceInWei; // Balance that will be used to fund the subscription's upkeep.
+  uint256 totalUpdates; // Tracks update count across all feeds in the subscription (increments by number of feeds per update)
+  uint256 totalSpent; // Counter of total fees paid for subscription upkeep in wei.
+}
+```
+
 ### UpdateCriteria
 
 This struct defines when price feeds should be updated:
 
 ```solidity
 struct UpdateCriteria {
-  bool updateOnHeartbeat; // Update based on time elapsed
+  bool updateOnHeartbeat; // Should update based on time elapsed
   uint32 heartbeatSeconds; // Time interval for heartbeat updates
-  bool updateOnDeviation; // Update based on price deviation
+  bool updateOnDeviation; // Should update on price deviation
   uint32 deviationThresholdBps; // Price deviation threshold in basis points
 }
 ```
@@ -93,13 +106,19 @@ uint256 minBalance = pulse.getMinimumBalance(uint8(params.priceIds.length));
 uint256 subscriptionId = pulse.createSubscription{value: minBalance}(params);
 ```
 
+## Updating a Subscription
+
+You can update an existing subscription's parameters using the `updateSubscription` method. Only the subscription manager (the address that created it) can update a subscription, and permanent subscriptions cannot be updated afterwards.
+
 ## Reading Price Feeds
 
 ```solidity
 bytes32[] memory priceIds = new bytes32[](1);
 priceIds[0] = bytes32(...);  // Pyth price feed ID
 
-PythStructs.Price[] memory prices = pulse.getPricesUnsafe(subscriptionId, priceIds);
+// Specify maximum age in seconds (e.g., 300 seconds = 5 minutes)
+uint256 maxAge = 300;
+PythStructs.Price[] memory prices = pulse.getPricesNoOlderThan(subscriptionId, priceIds, maxAge);
 
 // Access price data
 int64 price = prices[0].price;

target_chains/ethereum/pulse_sdk/solidity/SchedulerStructs.sol

@@ -2,27 +2,32 @@
 
 pragma solidity ^0.8.0;
 
+/// @title SchedulerStructs
+/// @notice Contains data structures used by the Pyth Pulse protocol
 contract SchedulerStructs {
+    /// @notice Parameters defining a Pulse subscription
     struct SubscriptionParams {
-        bytes32[] priceIds;
-        address[] readerWhitelist;
-        bool whitelistEnabled;
-        bool isActive;
-        bool isPermanent;
-        UpdateCriteria updateCriteria;
+        bytes32[] priceIds; // Array of Pyth price feed IDs to subscribe to
+        address[] readerWhitelist; // Optional array of addresses allowed to read prices
+        bool whitelistEnabled; // Whether to enforce whitelist or allow anyone to read
+        bool isActive; // Whether the subscription is active
+        bool isPermanent; // Whether the subscription can be updated
+        UpdateCriteria updateCriteria; // When to update the price feeds
     }
 
+    /// @notice Status information for a Pulse subscription
     struct SubscriptionStatus {
-        uint256 priceLastUpdatedAt;
-        uint256 balanceInWei;
-        uint256 totalUpdates;
-        uint256 totalSpent;
+        uint256 priceLastUpdatedAt; // Timestamp of the last update. All feeds in the subscription are updated together.
+        uint256 balanceInWei; // Balance that will be used to fund the subscription's upkeep.
+        uint256 totalUpdates; // Tracks update count across all feeds in the subscription (increments by number of feeds per update)
+        uint256 totalSpent; // Counter of total fees paid for subscription upkeep in wei.
     }
 
+    /// @notice Criteria for when price feeds should be updated
     struct UpdateCriteria {
-        bool updateOnHeartbeat;
-        uint32 heartbeatSeconds;
-        bool updateOnDeviation;
-        uint32 deviationThresholdBps;
+        bool updateOnHeartbeat; // Should update based on time elapsed
+        uint32 heartbeatSeconds; // Time interval for heartbeat updates
+        bool updateOnDeviation; // Should update based on price deviation
+        uint32 deviationThresholdBps; // Price deviation threshold in basis points
     }
 }