Merge pull request #20 from pyth-network/docs-refactor

Docs refactor

Author: ali-behjati

pyth-sdk-solana/src/state.rs

@@ -89,7 +89,8 @@ impl Default for CorpAction {
     }
 }
 
-/// The type of prices associated with a product -- each product may have multiple price feeds of different types.
+/// The type of prices associated with a product -- each product may have multiple price feeds of
+/// different types.
 #[derive(
     Copy,
     Clone,
@@ -210,10 +211,12 @@ unsafe impl Pod for ProductAccount {
 #[repr(C)]
 pub struct PriceInfo {
     /// the current price.
-    /// For the aggregate price use price.get_current_price() whenever possible. It has more checks to make sure price is valid.
+    /// For the aggregate price use price.get_current_price() whenever possible. It has more checks
+    /// to make sure price is valid.
     pub price:    i64,
     /// confidence interval around the price.
-    /// For the aggregate confidence use price.get_current_price() whenever possible. It has more checks to make sure price is valid.
+    /// For the aggregate confidence use price.get_current_price() whenever possible. It has more
+    /// checks to make sure price is valid.
     pub conf:     u64,
     /// status of price (Trading is valid).
     /// For the aggregate status use price.get_current_status() whenever possible.
@@ -388,7 +391,7 @@ fn load<T: Pod>(data: &[u8]) -> Result<&T, PodCastError> {
     }
 }
 
-/** Get a `Mapping` account from the raw byte value of a Solana account. */
+/// Get a `Mapping` account from the raw byte value of a Solana account.
 pub fn load_mapping_account(data: &[u8]) -> Result<&MappingAccount, PythError> {
     let pyth_mapping = load::<MappingAccount>(&data).map_err(|_| PythError::InvalidAccountData)?;
 
@@ -405,7 +408,7 @@ pub fn load_mapping_account(data: &[u8]) -> Result<&MappingAccount, PythError> {
     return Ok(pyth_mapping);
 }
 
-/** Get a `Product` account from the raw byte value of a Solana account. */
+/// Get a `Product` account from the raw byte value of a Solana account.
 pub fn load_product_account(data: &[u8]) -> Result<&ProductAccount, PythError> {
     let pyth_product = load::<ProductAccount>(&data).map_err(|_| PythError::InvalidAccountData)?;
 
@@ -422,7 +425,7 @@ pub fn load_product_account(data: &[u8]) -> Result<&ProductAccount, PythError> {
     return Ok(pyth_product);
 }
 
-/** Get a `Price` account from the raw byte value of a Solana account. */
+/// Get a `Price` account from the raw byte value of a Solana account.
 pub fn load_price_account(data: &[u8]) -> Result<&PriceAccount, PythError> {
     let pyth_price = load::<PriceAccount>(&data).map_err(|_| PythError::InvalidAccountData)?;
 

pyth-sdk-solana/test-contract/src/instruction.rs

@@ -44,8 +44,9 @@ pub enum PythClientInstruction {
     Noop,
 
     PriceStatusCheck {
-        // A Price serialized as a vector of bytes. This field is stored as a vector of bytes (instead of a Price)
-        // so that we do not have to add Borsh serialization to all structs, which is expensive.
+        // A Price serialized as a vector of bytes. This field is stored as a vector of bytes
+        // (instead of a Price) so that we do not have to add Borsh serialization to all
+        // structs, which is expensive.
         price_account_data:    Vec<u8>,
         expected_price_status: PriceStatus,
     },

pyth-sdk-solana/test-contract/tests/stale_price.rs

@@ -86,9 +86,9 @@ async fn test_price_not_stale() {
 async fn test_price_stale() {
     let mut price = price_account_all_zero();
     price.agg.status = PriceStatus::Trading;
-    // Value 100 will cause an overflow because this is bigger than Solana slot in the test suite (its ~1-5).
-    // As the check will be 5u - 100u ~= 1e18 > MAX_SLOT_DIFFERENCE. It can only break when Solana slot in the test suite becomes
-    // between 100 and 100+MAX_SLOT_DIFFERENCE.
+    // Value 100 will cause an overflow because this is bigger than Solana slot in the test suite
+    // (its ~1-5). As the check will be 5u - 100u ~= 1e18 > MAX_SLOT_DIFFERENCE. It can only
+    // break when Solana slot in the test suite becomes between 100 and 100+MAX_SLOT_DIFFERENCE.
     price.agg.pub_slot = 100;
     test_instr_exec_ok(instruction::price_status_check(
         &price,

pyth-sdk/Cargo.toml

@@ -6,7 +6,7 @@ edition = "2018"
 license = "Apache-2.0"
 homepage = "https://pyth.network"
 repository = "https://github.com/pyth-network/pyth-sdk-rs"
-description = "pyth price oracle data structures and example usage"
+description = "Data structures and utilites for the Pyth price oracle"
 keywords = [ "pyth", "oracle" ]
 readme = "README.md"
 

pyth-sdk/src/lib.rs

@@ -8,6 +8,7 @@ use schemars::JsonSchema;
 mod price_conf;
 pub use price_conf::PriceConf;
 
+/// Consists of 32 bytes and it is currently based on largest Public Key size on various blockchains.
 pub type ProductIdentifier = [u8; 32];
 
 /// Represents availability status of a price feed.
@@ -63,26 +64,27 @@ pub struct Price {
     pub conf:               u64,
     /// Status of price (Trading is valid).
     pub status:             PriceStatus,
-    /// price exponent
+    /// Price exponent.
     pub expo:               i32,
-    /// maximum number of allowed publishers that can contribute to a price
+    /// Maximum number of allowed publishers that can contribute to a price.
     pub max_num_publishers: u32,
-    /// number of publishers that made up current aggregate
+    /// Number of publishers that made up current aggregate.
     pub num_publishers:     u32,
-    /// exponentially moving average price
+    /// Exponentially moving average price.
     pub ema_price:          i64,
-    /// exponentially moving average confidence interval
+    /// Exponentially moving average confidence interval.
     pub ema_conf:           u64,
-    /// product account key
+    /// Product account key.
     pub product_id:         ProductIdentifier,
 }
 
 impl Price {
-    /**
-     * Get the current price and confidence interval as fixed-point numbers of the form a * 10^e.
-     * Returns a struct containing the current price, confidence interval, and the exponent for both
-     * numbers. Returns `None` if price information is currently unavailable for any reason.
-     */
+    /// Get the current price and confidence interval as fixed-point numbers of the form a *
+    /// 10^e.
+    /// 
+    /// Returns a struct containing the current price, confidence interval, and the exponent for
+    /// both numbers. Returns `None` if price information is currently unavailable for any
+    /// reason.
     pub fn get_current_price(&self) -> Option<PriceConf> {
         if !matches!(self.status, PriceStatus::Trading) {
             None
@@ -95,13 +97,12 @@ impl Price {
         }
     }
 
-    /**
-     * Get the exponential moving average price (ema_price) and a confidence interval on the result.
-     * Returns `None` if the ema price is currently unavailable.
-     *
-     * At the moment, the confidence interval returned by this method is computed in
-     * a somewhat questionable way, so we do not recommend using it for high-value applications.
-     */
+    /// Get the exponential moving average price (ema_price) and a confidence interval on the
+    /// result.
+    /// 
+    /// Returns `None` if the ema price is currently unavailable.
+    /// At the moment, the confidence interval returned by this method is computed in
+    /// a somewhat questionable way, so we do not recommend using it for high-value applications.
     pub fn get_ema_price(&self) -> Option<PriceConf> {
         // This method currently cannot return None, but may do so in the future.
         Some(PriceConf {
@@ -111,25 +112,24 @@ impl Price {
         })
     }
 
-    /**
-     * Get the current price of this account in a different quote currency. If this account
-     * represents the price of the product X/Z, and `quote` represents the price of the product Y/Z,
-     * this method returns the price of X/Y. Use this method to get the price of e.g., mSOL/SOL from
-     * the mSOL/USD and SOL/USD accounts.
-     *
-     * `result_expo` determines the exponent of the result, i.e., the number of digits below the decimal
-     * point. This method returns `None` if either the price or confidence are too large to be
-     * represented with the requested exponent.
-     *
-     * Example:
-     * ```ignore
-     * let btc_usd: Price = ...;
-     * let eth_usd: Price = ...;
-     * // -8 is the desired exponent for the result
-     * let btc_eth: PriceConf = btc_usd.get_price_in_quote(&eth_usd, -8);
-     * println!("BTC/ETH price: ({} +- {}) x 10^{}", price.price, price.conf, price.expo);
-     * ```
-     */
+    /// Get the current price of this account in a different quote currency.
+    /// 
+    /// If this account represents the price of the product X/Z, and `quote` represents the price
+    /// of the product Y/Z, this method returns the price of X/Y. Use this method to get the
+    /// price of e.g., mSOL/SOL from the mSOL/USD and SOL/USD accounts.
+    /// 
+    /// `result_expo` determines the exponent of the result, i.e., the number of digits below the
+    /// decimal point. This method returns `None` if either the price or confidence are too
+    /// large to be represented with the requested exponent.
+    /// 
+    /// Example:
+    /// ```ignore
+    /// let btc_usd: Price = ...;
+    /// let eth_usd: Price = ...;
+    /// // -8 is the desired exponent for the result
+    /// let btc_eth: PriceConf = btc_usd.get_price_in_quote(&eth_usd, -8);
+    /// println!("BTC/ETH price: ({} +- {}) x 10^{}", price.price, price.conf, price.expo);
+    /// ```
     pub fn get_price_in_quote(&self, quote: &Price, result_expo: i32) -> Option<PriceConf> {
         match (self.get_current_price(), quote.get_current_price()) {
             (Some(base_price_conf), Some(quote_price_conf)) => base_price_conf
@@ -139,28 +139,27 @@ impl Price {
         }
     }
 
-    /**
-     * Get the price of a basket of currencies. Each entry in `amounts` is of the form
-     * `(price, qty, qty_expo)`, and the result is the sum of `price * qty * 10^qty_expo`.
-     * The result is returned with exponent `result_expo`.
-     *
-     * An example use case for this function is to get the value of an LP token.
-     *
-     * Example:
-     * ```ignore
-     * let btc_usd: Price = ...;
-     * let eth_usd: Price = ...;
-     * // Quantity of each asset in fixed-point a * 10^e.
-     * // This represents 0.1 BTC and .05 ETH.
-     * // -8 is desired exponent for result
-     * let basket_price: PriceConf = Price::price_basket(&[
-     *     (btc_usd, 10, -2),
-     *     (eth_usd, 5, -2)
-     *   ], -8);
-     * println!("0.1 BTC and 0.05 ETH are worth: ({} +- {}) x 10^{} USD",
-     *          basket_price.price, basket_price.conf, basket_price.expo);
-     * ```
-     */
+    /// Get the price of a basket of currencies.
+    ///
+    /// Each entry in `amounts` is of the form `(price, qty, qty_expo)`, and the result is the sum 
+    /// of `price * qty * 10^qty_expo`. The result is returned with exponent `result_expo`.
+    ///
+    /// An example use case for this function is to get the value of an LP token.
+    ///
+    /// Example:
+    /// ```ignore
+    /// let btc_usd: Price = ...;
+    /// let eth_usd: Price = ...;
+    /// // Quantity of each asset in fixed-point a * 10^e.
+    /// // This represents 0.1 BTC and .05 ETH.
+    /// // -8 is desired exponent for result
+    /// let basket_price: PriceConf = Price::price_basket(&[
+    ///     (btc_usd, 10, -2),
+    ///     (eth_usd, 5, -2)
+    ///   ], -8);
+    /// println!("0.1 BTC and 0.05 ETH are worth: ({} +- {}) x 10^{} USD",
+    ///          basket_price.price, basket_price.conf, basket_price.expo);
+    /// ```
     pub fn price_basket(amounts: &[(Price, i64, i32)], result_expo: i32) -> Option<PriceConf> {
         assert!(amounts.len() > 0);
         let mut res = PriceConf {