Add explanatory comments (#335)

* Add explanatory comments

* Add second best practices link

Author: tompntn

aptos/contracts/sources/pyth.move

@@ -131,6 +131,10 @@ module pyth::pyth {
     /// Update the cached price feeds with the data in the given VAAs.
     /// The vaas argument is a vector of VAAs encoded as bytes.
     /// 
+    /// The javascript https://github.com/pyth-network/pyth-js/tree/main/pyth-aptos-js package
+    /// should be used to fetch these VAAs from the Price Service. More information about this
+    /// process can be found at https://docs.pyth.network/consume-data.
+    /// 
     /// The given fee must contain a sufficient number of coins to pay the update fee.
     /// The update fee amount can be queried by calling get_update_fee().
     public fun update_price_feeds(vaas: vector<vector<u8>>, fee: Coin<AptosCoin>) {
@@ -264,9 +268,16 @@ module pyth::pyth {
     /// Get the latest available price cached for the given price identifier, if that price is 
     /// no older than the stale price threshold.
     /// 
+    /// Please refer to the documentation at https://docs.pyth.network/consumers/best-practices for
+    /// how to how this price safely.
+    /// 
     /// Important: it is recommended to call update_price_feeds() to update the cached price
     /// before calling this function, as get_price() will abort if the cached price is older 
     /// than the stale price threshold.
+    /// 
+    /// Note that the price_identifier does not correspond to a seperate Aptos account:
+    /// all price feeds are stored in the single pyth account. The price identifier is an
+    /// opaque identifier for a price feed.
     public fun get_price(price_identifier: PriceIdentifier): Price {
         get_price_no_older_than(price_identifier, state::get_stale_price_threshold_secs())
     }

aptos/contracts/sources/state.move

@@ -38,6 +38,10 @@ module pyth::state {
     }
 
     /// Mapping of cached price information
+    /// 
+    /// WARNING: do not directly read out of this table, instead use 
+    /// the checked `pyth::get_price` method. This ensures that the price
+    /// is recent enough.
     struct LatestPriceInfo has key {
         info: Table<PriceIdentifier, PriceInfo>,
     }

aptos/example/sources/example.move

@@ -6,6 +6,10 @@ module example::example {
 
     /// Updates the Pyth price feeds using the given pyth_update_data, and then returns 
     /// the BTC/USD price.
+    /// 
+    /// https://github.com/pyth-network/pyth-js/tree/main/pyth-aptos-js should be used to 
+    /// fetch the pyth_update_data off-chain and pass it in. More information about how this
+    /// works can be found at https://docs.pyth.network/consume-data
     public fun get_btc_usd_price(user: &signer, pyth_update_data: vector<vector<u8>>): Price {
 
         // First update the Pyth price feeds