docstrings edited and added

Author: Bengt Lofgren

solana/modules/matching-engine-testing/tests/shimful/fast_market_order_shim.rs

@@ -33,16 +33,14 @@ use wormhole_io::TypePrefixedPayload;
 /// # Arguments
 ///
 /// * `testing_context` - The testing context
-/// * `payer_signer` - The payer signer keypair
-/// * `fast_market_order` - The fast market order state
-/// * `guardian_set_pubkey` - The guardian set pubkey
-/// * `guardian_signatures_pubkey` - The guardian signatures pubkey
-/// * `guardian_set_bump` - The guardian set bump
+/// * `test_context` - The program test context
 /// * `expected_error` - The expected error
+/// * `current_state` - The current testing engine state
+/// * `config` - The initialization configuration
 ///
-/// # Asserts
+/// # Returns
 ///
-/// * The expected error, if any, is reached when executing the instruction
+/// * `TestingEngineState` - The updated testing engine state
 pub async fn initialize_fast_market_order_shimful(
     testing_context: &TestingContext,
     test_context: &mut ProgramTestContext,
@@ -134,9 +132,7 @@ pub async fn initialize_fast_market_order_shimful(
 /// * `payer_signer` - The payer signer keypair
 /// * `program_id` - The program id
 /// * `fast_market_order` - The fast market order state
-/// * `guardian_set_pubkey` - The guardian set pubkey
-/// * `guardian_signatures_pubkey` - The guardian signatures pubkey
-/// * `guardian_set_bump` - The guardian set bump
+/// * `guardian_signature_info` - Information about guardian signatures
 ///
 /// # Returns
 ///
@@ -184,7 +180,8 @@ pub fn initialize_fast_market_order_shimful_instruction(
 /// # Arguments
 ///
 /// * `testing_context` - The testing context
-/// * `refund_recipient_keypair` - The refund recipient keypair that will receive the refund after closing the fast market order account
+/// * `test_context` - The program test context
+/// * `refund_recipient_keypair` - The refund recipient keypair that will receive the refund
 /// * `fast_market_order_address` - The fast market order account address
 /// * `expected_error` - The expected error
 ///

solana/modules/matching-engine-testing/tests/shimful/shims_execute_order.rs

@@ -215,6 +215,17 @@ pub fn create_execute_order_fallback_fixture(
     }
 }
 
+/// Create the execute order shim accounts
+///
+/// # Arguments
+///
+/// * `execute_order_fallback_accounts` - The execute order fallback accounts
+/// * `execute_order_fallback_fixture` - The execute order fallback fixture
+/// * `clock_id` - The clock id
+///
+/// # Returns
+///
+/// The execute order shim accounts
 pub fn create_execute_order_shim_accounts<'ix>(
     execute_order_fallback_accounts: &'ix ExecuteOrderFallbackAccounts,
     execute_order_fallback_fixture: &'ix ExecuteOrderFallbackFixture,

solana/modules/matching-engine-testing/tests/shimful/shims_make_offer.rs

@@ -90,6 +90,20 @@ pub async fn place_initial_offer_shimful(
     .await
 }
 
+/// Evaluate the place initial offer shimful state
+///
+/// # Arguments
+///
+/// * `testing_context` - The testing context
+/// * `test_context` - The test context
+/// * `current_state` - The current state
+/// * `config` - The config
+/// * `actor_usdc_balance_before` - The actor USDC balance before
+/// * `place_initial_offer_accounts` - The place initial offer shimful accounts
+///
+/// # Returns
+///
+/// The testing engine state after the place initial offer shimful instruction
 pub async fn evaluate_place_initial_offer_shimful_state(
     testing_context: &TestingContext,
     test_context: &mut ProgramTestContext,
@@ -170,6 +184,20 @@ pub async fn evaluate_place_initial_offer_shimful_state(
     current_state.clone()
 }
 
+/// Place the initial offer shimful instruction
+///
+/// Creates the place initial offer shimful instruction
+///
+/// # Arguments
+///
+/// * `testing_context` - The testing context
+/// * `test_context` - The test context
+/// * `current_state` - The current state
+/// * `config` - The config
+///
+/// # Returns
+///
+/// The place initial offer shimful instruction
 pub async fn place_initial_offer_shimful_instruction(
     testing_context: &TestingContext,
     test_context: &mut ProgramTestContext,

solana/modules/matching-engine-testing/tests/shimful/shims_prepare_order_response.rs

@@ -145,15 +145,38 @@ impl PrepareOrderResponseShimAccountsFixture {
     }
 }
 
-pub struct PrepareOrderResponseShimDataFixture {
+/// Prepare order response shim data helper
+///
+/// This struct is a helper struct used to create the data for the prepare order response instruction
+///
+/// # Fields
+///
+/// * `encoded_cctp_message` - The encoded CCTP message
+/// * `cctp_attestation` - The CCTP attestation
+/// * `finalized_vaa_message_args` - The finalized VAA message args
+/// * `fast_market_order` - The fast market order
+pub struct PrepareOrderResponseShimDataHelper {
     pub encoded_cctp_message: Vec<u8>,
     pub cctp_attestation: Vec<u8>,
     pub finalized_vaa_message_args: FinalizedVaaMessageArgs,
     pub fast_market_order: FastMarketOrderState,
 }
 
-// Helper struct for creating the data for the prepare order response instruction
-impl PrepareOrderResponseShimDataFixture {
+impl PrepareOrderResponseShimDataHelper {
+    /// Create a new prepare order response shim data helper
+    ///
+    /// # Arguments
+    ///
+    /// * `encoded_cctp_message` - The encoded CCTP message
+    /// * `cctp_attestation` - The CCTP attestation
+    /// * `consistency_level` - The consistency level
+    /// * `base_fee` - The base fee
+    /// * `fast_market_order` - The fast market order
+    /// * `guardian_set_bump` - The guardian set bump
+    ///
+    /// # Returns
+    ///
+    /// The prepare order response shim data helper
     pub fn new(
         encoded_cctp_message: Vec<u8>,
         cctp_attestation: Vec<u8>,
@@ -183,12 +206,25 @@ impl PrepareOrderResponseShimDataFixture {
 }
 
 /// Executes the instruction that prepares the order response for the CCTP shim
+///
+/// # Arguments
+///
+/// * `testing_context` - The testing context
+/// * `test_context` - The test context
+/// * `payer_signer` - The payer signer
+/// * `accounts` - The prepare order response shim accounts
+/// * `data` - The prepare order response shim data
+/// * `expected_error` - The expected error
+///
+/// # Returns
+///
+/// The prepare order response shim fixture
 pub async fn prepare_order_response_cctp_shim(
     testing_context: &TestingContext,
     test_context: &mut ProgramTestContext,
     payer_signer: &Rc<Keypair>,
     accounts: PrepareOrderResponseShimAccountsFixture,
-    data: PrepareOrderResponseShimDataFixture,
+    data: PrepareOrderResponseShimDataHelper,
     expected_error: Option<&ExpectedError>,
 ) -> Option<PrepareOrderResponseShimFixture> {
     let matching_engine_program_id = &testing_context.get_matching_engine_program_id();
@@ -280,6 +316,20 @@ pub async fn prepare_order_response_cctp_shim(
     }
 }
 
+/// Prepare order response test
+///
+/// Executes the prepare order response instruction in a testing context
+///
+/// # Arguments
+///
+/// * `testing_context` - The testing context
+/// * `test_context` - The test context
+/// * `config` - The prepare order response instruction config
+/// * `current_state` - The current state
+///
+/// # Returns
+///
+/// The prepare order response shim fixture (none if failed)
 pub async fn prepare_order_response_test(
     testing_context: &TestingContext,
     test_context: &mut ProgramTestContext,
@@ -337,7 +387,7 @@ pub async fn prepare_order_response_test(
         .unwrap();
 
     let deposit_base_fee = utils::cctp_message::get_deposit_base_fee(&deposit);
-    let prepare_order_response_cctp_shim_data = PrepareOrderResponseShimDataFixture::new(
+    let prepare_order_response_cctp_shim_data = PrepareOrderResponseShimDataHelper::new(
         cctp_token_burn_message.encoded_cctp_burn_message,
         cctp_token_burn_message.cctp_attestation,
         deposit_vaa_data.consistency_level,

solana/modules/matching-engine-testing/tests/testing_engine/engine.rs

@@ -391,6 +391,10 @@ impl TestingEngine {
         }
     }
 
+    // --------------------------------------------------------------------------------------------
+    // Instruction trigger functions
+    // --------------------------------------------------------------------------------------------
+
     /// Creates the initial state for the testing engine
     pub fn create_initial_state(&self) -> TestingEngineState {
         let fixture_accounts = self
@@ -536,6 +540,8 @@ impl TestingEngine {
             order_executed: current_state.order_executed().cloned(),
         }
     }
+
+    /// Instruction trigger function for placing an initial offer
     async fn place_initial_offer_shimless(
         &self,
         test_context: &mut ProgramTestContext,
@@ -860,6 +866,10 @@ impl TestingEngine {
         }
     }
 
+    // --------------------------------------------------------------------------------------------
+    // Verification trigger functions
+    // --------------------------------------------------------------------------------------------
+
     async fn verify_auction_state(
         &self,
         test_context: &mut ProgramTestContext,
@@ -923,6 +933,10 @@ impl TestingEngine {
         current_state.clone()
     }
 
+    // --------------------------------------------------------------------------------------------
+    // Combination trigger functions
+    // --------------------------------------------------------------------------------------------
+
     async fn create_fast_market_order_and_place_initial_offer(
         &self,
         test_context: &mut ProgramTestContext,
@@ -1038,6 +1052,10 @@ impl TestingEngine {
         .await
     }
 
+    // --------------------------------------------------------------------------------------------
+    // Helper functions for manipulating the state
+    // --------------------------------------------------------------------------------------------
+
     pub async fn make_auction_passed_penalty_period(
         &self,
         test_context: &mut ProgramTestContext,