From 099cf9d9ffda459120f48beee173b12cdfe03a56 Mon Sep 17 00:00:00 2001 From: Divine-designs Date: Mon, 29 Jun 2026 17:50:42 +0100 Subject: [PATCH] docs(course_access): complete save_user_profile docstring with Returns section Closes #206. Brings `save_user_profile` docstring in line with the template requested in the issue: description, Arguments, and Returns. The existing docstring was missing the `# Returns` section and did not explain the side effects (persistent storage write + saveUsPrl event emission) or the failure mode (empty off_chain_ref_id halts execution via handle_error). All three are now documented. `save_user_profile` is the only public function in the file. --- .../src/functions/save_profile.rs | 28 ++++++++++++------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/contracts/course/course_access/src/functions/save_profile.rs b/contracts/course/course_access/src/functions/save_profile.rs index 103199a..be85497 100644 --- a/contracts/course/course_access/src/functions/save_profile.rs +++ b/contracts/course/course_access/src/functions/save_profile.rs @@ -11,18 +11,26 @@ const SAVE_USER_PROFILE_EVENT: Symbol = symbol_short!("saveUsPrl"); /// Save a minimal on-chain user profile. /// -/// Stores only the user's address and an off-chain reference ID. -/// All PII (name, email, profession, goals, country) is stored off-chain. +/// Stores only the user's address and an off-chain reference ID under +/// `DataKey::UserProfile(user)` in persistent storage and emits a +/// `saveUsPrl` event with `(user, off_chain_ref_id)`. All PII (name, +/// email, profession, goals, country) lives off-chain and is keyed by +/// `off_chain_ref_id`. /// /// # Arguments -/// * `env` - Soroban environment -/// * `off_chain_ref_id` - UUID/hash mapping to the user's full record in the off-chain DB -/// * `user` - The user's blockchain address -pub fn save_user_profile( - env: Env, - off_chain_ref_id: String, - user: Address, -) { +/// +/// * `env` - The Soroban environment for storage and event access. +/// * `off_chain_ref_id` - UUID or hash mapping to the user's full record +/// in the off-chain database. Must be non-empty. +/// * `user` - The user's blockchain address that the profile belongs to. +/// +/// # Returns +/// +/// * `()` - The function returns the unit type on success. On failure +/// (empty `off_chain_ref_id`) it does not return — `handle_error` +/// raises `Error::OffChainRefIdRequired`, which halts contract +/// execution with the corresponding error code. +pub fn save_user_profile(env: Env, off_chain_ref_id: String, user: Address) { // Validate required field if off_chain_ref_id.is_empty() { handle_error(&env, Error::OffChainRefIdRequired)