chore: add more docs

Author: ali-bahjati

program/c/src/oracle/model/price_model.c

@@ -43,6 +43,22 @@ void heapsort(int64_t * a, uint64_t n) {
   }
 }
 
+/*
+ * Find the 25, 50, and 75 percentiles of the given quotes using heapsort.
+ *
+ * This implementation optimizes the price_model_core function for minimal compute unit usage in BPF.
+ *
+ * In Solana, each BPF instruction costs 1 unit of compute and is much different than a native code
+ * execution time. Here are some of the differences:
+ * 1. There is no cache, so memory access is much more expensive.
+ * 2. The instruction set is very minimal, and there are only 10 registers available.
+ * 3. The BPF compiler is not very good at optimizing the code.
+ * 4. The stack size is limited and having extra stack frame has high overhead.
+ *
+ * This implementation is chosen among other implementations such as merge-sort, quick-sort, and quick-select
+ * because it is very fast, has small number of instructions, and has a very small memory footprint by being
+ * in-place and is non-recursive.
+ */
 int64_t *
 price_model_core( uint64_t  cnt,
                   int64_t * quote,

program/c/src/oracle/model/price_model.h

@@ -8,8 +8,16 @@
 extern "C" {
 #endif
 
+/*
+ * This function computes the p25, p50 and p75 percentiles of the given quotes and
+ * writes them to the given pointers. It also returns the sorted quotes array. Being
+ * sorted is not necessary for this model to work, and is only relied upon by the
+ * tests to verify the correctness of the model with more confidence.
+ *
+ * The quote array might get modified by this function.
+ */
 int64_t *
-price_model_core( uint64_t  cnt,       /* Assumes price_model_cnt_valid( cnt ) is true */
+price_model_core( uint64_t  cnt,       /* Number of elements in quote */
                   int64_t * quote,     /* Assumes quote[i] for i in [0,cnt) is the i-th quote on input */
                   int64_t * _p25,      /* Assumes *_p25 is safe to write to the p25 model output */
                   int64_t * _p50,      /* Assumes *_p50 " */

program/c/src/oracle/model/test_price_model.c

@@ -39,6 +39,9 @@ int test_price_model() {
 
     /* Validate the results */
 
+    /*
+     * Although being sorted is not necessary it gives us more confidence about the correctness of the model.
+     */
     qsort( quote0, (size_t)cnt, sizeof(int64_t), qcmp );
     if( memcmp( quote, quote0, sizeof(int64_t)*(size_t)cnt ) ) { printf( "FAIL (sort)\n" ); return 1; }
 

program/rust/src/tests/test_benchmark.rs

@@ -36,7 +36,7 @@ async fn run_benchmark(num_publishers: usize) -> Result<(), Box<dyn std::error::
         sim.add_publisher(&price_keypair, *publisher).await?;
     }
 
-    // Set the seed to make the test deterministic
+    // Set the seed to make the test is deterministic
     let mut rnd = rand::rngs::SmallRng::seed_from_u64(14);
 
     for kp in publishers_keypairs.iter() {