Closes 2 issues

contracts/course/course_access/src/functions/contract_versioning.rs

@@ -26,7 +26,15 @@ pub enum VersioningError {
 const VERSION_HISTORY_KEY: &str = "version_history";
 const MIGRATION_STATUS_KEY: &str = "migration_status";
 
-
+/// Brief description: Retrieves the version history of migrations.
+///
+/// # Arguments
+///
+/// * `env` - The environment context.
+///
+/// # Returns
+///
+/// * `Vec<String>` - A vector containing the history of versions.
 pub fn get_version_history(env: &Env) -> Vec<String> {
     let key = String::from_str(env, VERSION_HISTORY_KEY);
     env.storage()
@@ -35,6 +43,16 @@ pub fn get_version_history(env: &Env) -> Vec<String> {
         .unwrap_or_else(|| vec![env])
 }
 
+/// Brief description: Stores a new version in the migration history.
+///
+/// # Arguments
+///
+/// * `env` - The environment context.
+/// * `version` - The version string to store in history.
+///
+/// # Returns
+///
+/// * `()` - This function does not return a value.
 fn store_version_in_history(env: &Env, version: String) {
     let mut history: Vec<String> = get_version_history(env);
     history.push_back(version.clone());
@@ -43,7 +61,16 @@ fn store_version_in_history(env: &Env, version: String) {
     env.storage().instance().set(&key, &history);
 }
 
-
+/// Brief description: Checks if a specific version exists in history.
+///
+/// # Arguments
+///
+/// * `env` - The environment context.
+/// * `version` - The version string to check.
+///
+/// # Returns
+///
+/// * `bool` - True if the version exists in history, otherwise false.
 fn version_exists_in_history(env: &Env, version: &String) -> bool {
     let history: Vec<String> = get_version_history(env);
     for v in history.iter() {
@@ -54,7 +81,15 @@ fn version_exists_in_history(env: &Env, version: &String) -> bool {
     false
 }
 
-
+/// Brief description: Retrieves the migration status.
+///
+/// # Arguments
+///
+/// * `env` - The environment context.
+///
+/// # Returns
+///
+/// * `String` - The current status of migrations.
 pub fn get_migration_status(env: &Env) -> String {
     let key: String = String::from_str(env, MIGRATION_STATUS_KEY);
     env.storage()
@@ -63,20 +98,48 @@ pub fn get_migration_status(env: &Env) -> String {
         .unwrap_or_else(|| String::from_str(env, "No migrations pending"))
 }
 
-
+/// Brief description: Sets the migration status.
+///
+/// # Arguments
+///
+/// * `env` - The environment context.
+/// * `status` - The status string to set.
+///
+/// # Returns
+///
+/// * `()` - This function does not return a value.
 fn set_migration_status(env: &Env, status: String) {
     let key = String::from_str(env, MIGRATION_STATUS_KEY);
     env.storage().instance().set(&key, &status);
 }
 
-
+/// Brief description: Checks if a migration from one version to another is compatible.
+///
+/// # Arguments
+///
+/// * `_env` - The environment context (unused).
+/// * `_from_version` - The source version string (unused).
+/// * `_to_version` - The destination version string (unused).
+///
+/// # Returns
+///
+/// * `bool` - True, indicating all versions are compatible.
 pub fn is_version_compatible(_env: &Env, _from_version: String, _to_version: String) -> bool {
     // Simple compatibility check - for now, assume all versions are compatible
     // In a real implementation, you would parse semantic versions properly
     true
 }
 
-
+/// Brief description: Checks if the caller is authorized to perform migrations.
+///
+/// # Arguments
+///
+/// * `_env` - The environment context (unused).
+/// * `_caller` - The address of the caller (unused).
+///
+/// # Returns
+///
+/// * `bool` - True, indicating that all authenticated users are allowed to migrate.
 fn is_authorized_for_migration(_env: &Env, _caller: Address) -> bool {
     // For now, we'll allow any authenticated user
     // In a real implementation, you would check against user management contract
@@ -90,6 +153,18 @@ fn is_authorized_for_migration(_env: &Env, _caller: Address) -> bool {
     true // Placeholder - allow all authenticated users
 }
 
+/// Brief description: Performs a migration of access data between versions.
+///
+/// # Arguments
+///
+/// * `env` - The environment context.
+/// * `caller` - The address of the caller.
+/// * `from_version` - The source version to migrate from.
+/// * `to_version` - The destination version to migrate to.
+///
+/// # Returns
+///
+/// * `bool` - True if the migration was successful, otherwise false.
 pub fn migrate_access_data(
     env: &Env,
     caller: Address,
@@ -136,7 +211,17 @@ pub fn migrate_access_data(
     }
 }
 
-/// Perform the actual access data migration between versions
+/// Brief description: Performs the actual migration of access data from one version to another.
+///
+/// # Arguments
+///
+/// * `env` - The environment context.
+/// * `_from_version` - The source version string (unused).
+/// * `_to_version` - The destination version string (unused).
+///
+/// # Returns
+///
+/// * `bool` - True, if the migration was successful; false otherwise.
 fn perform_access_data_migration(env: &Env, _from_version: &String, _to_version: &String) -> bool {
     // This is a placeholder for actual access data migration logic
     // In a real implementation, this would:
@@ -148,7 +233,15 @@ fn perform_access_data_migration(env: &Env, _from_version: &String, _to_version:
     migrate_access_v1_0_0_to_v1_1_0(env)
 }
 
-/// Migrate access data from version 1.0.0 to 1.1.0
+/// Brief description: Migrate access data from version 1.0.0 to 1.1.0.
+///
+/// # Arguments
+///
+/// * `_env` - The environment context (unused).
+///
+/// # Returns
+///
+/// * `bool` - True, indicating a successful migration.
 fn migrate_access_v1_0_0_to_v1_1_0(_env: &Env) -> bool {
     // Placeholder for access migration logic
     // This would typically involve:
@@ -161,7 +254,18 @@ fn migrate_access_v1_0_0_to_v1_1_0(_env: &Env) -> bool {
 }
 
 
-/// Emit a migration event
+/// Brief description: Emits a migration event.
+///
+/// # Arguments
+///
+/// * `_env` - The environment context (unused).
+/// * `_from_version` - The source version string (unused).
+/// * `_to_version` - The destination version string (unused).
+/// * `_success` - A boolean indicating if the migration was successful (unused).
+///
+/// # Returns
+///
+/// * `()` - This function does not return a value.
 fn emit_migration_event(_env: &Env, _from_version: &String, _to_version: &String, _success: bool) {
     // In a real implementation, you would emit events here
     // For now, we'll just set a status message

contracts/course/course_access/src/functions/utils/storage_utils.rs

@@ -9,7 +9,16 @@ use crate::functions::config::{TTL_BUMP, TTL_TTL};
 
 const TEMP_TTL: u32 = 900; // 15 minutes
 
-
+/// Brief description: Retrieves or creates the user's courses.
+///
+/// # Arguments
+///
+/// * `env` - The environment context.
+/// * `user` - The address of the user.
+///
+/// # Returns
+///
+/// * `UserCourses` - The user's courses, either retrieved from cache or created.
 pub fn get_or_create_user_courses(
     env: &Env,
     user: &Address,
@@ -37,7 +46,16 @@ pub fn get_or_create_user_courses(
     user_courses
 }
 
-
+/// Brief description: Retrieves or creates the list of users for a given course.
+///
+/// # Arguments
+///
+/// * `env` - The environment context.
+/// * `course_id` - The ID of the course.
+///
+/// # Returns
+///
+/// * `CourseUsers` - The users enrolled in the course, either retrieved from cache or created.
 pub fn get_or_create_course_users(
     env: &Env,
     course_id: &String,
@@ -65,7 +83,18 @@ pub fn get_or_create_course_users(
     course_users
 }
 
-
+/// Brief description: Updates access mappings for a user in a course.
+///
+/// # Arguments
+///
+/// * `env` - The environment context.
+/// * `course_id` - The ID of the course.
+/// * `user` - The address of the user.
+/// * `add` - A boolean flag indicating whether to grant (true) or revoke (false) access.
+///
+/// # Returns
+///
+/// * `()` - This function does not return a value.
 pub fn update_access_mappings(
     env: &Env,
     course_id: &String,
@@ -105,7 +134,17 @@ pub fn update_access_mappings(
     env.storage().temporary().set(&temp_course_key, &course_users);
 }
 
-
+/// Brief description: Checks if a user has access to a course.
+///
+/// # Arguments
+///
+/// * `env` - The environment context.
+/// * `course_id` - The ID of the course.
+/// * `user` - The address of the user.
+///
+/// # Returns
+///
+/// * `bool` - True if the user has access to the course, otherwise false.
 pub fn has_course_access(
     env: &Env,
     course_id: &String,
@@ -134,7 +173,16 @@ pub fn has_course_access(
     has_access
 }
 
-
+/// Brief description: Invalidates the cache for a specific course's users.
+///
+/// # Arguments
+///
+/// * `env` - The environment context.
+/// * `course_id` - The ID of the course.
+///
+/// # Returns
+///
+/// * `()` - This function does not return a value.
 pub fn invalidate_course_access_cache(
     env: &Env,
     course_id: &String,
@@ -149,4 +197,4 @@ pub fn invalidate_user_access_cache(
 ) {
     let temp_courses_key = (symbol_short!("temp_user_courses"), user.clone());
     env.storage().temporary().remove(&temp_courses_key);
-}
+}