Refactor to iterator-based API pattern and add documentation

- Changed from Dmod_ReadModules to OpenModules/ReadModule/CloseModules pattern
- Added Doxygen documentation for Dmod_ModuleState_t enum
- Added Doxygen documentation for Dmod_ModuleInfo_t struct
- Added Dmod_ModulesIterator_t opaque handle type
- Updated example application to use new API
- Updated unit tests (8 tests passing)
- Memory efficient: no large array allocation required

Co-authored-by: JohnAmadis <17320783+JohnAmadis@users.noreply.github.com>

Author: Copilot

examples/system/list_modules/main.c

@@ -5,7 +5,7 @@
 /**
  * @brief Simple test application to list all modules
  * 
- * This application demonstrates the usage of Dmod_ReadModules API
+ * This application demonstrates the usage of Dmod_OpenModules/ReadModule/CloseModules API
  */
 int main( int argc, char *argv[] )
 {
@@ -36,53 +36,63 @@ int main( int argc, char *argv[] )
         printf("\n");
     }
 
-    // Allocate array for module info
-    Dmod_ModuleInfo_t modules[100];
-    size_t count = Dmod_ReadModules( modules, 100 );
+    // Open modules iterator
+    Dmod_ModulesIterator_t iterator = Dmod_OpenModules();
+    if( iterator == NULL )
+    {
+        printf("Error: Failed to open modules iterator\n");
+        return -1;
+    }
 
-    printf("Found %zu modules:\n\n", count);
+    printf("Listing modules:\n\n");
+    printf("%-30s %-15s %-15s\n", "Module Name", "Version", "State");
+    printf("%-30s %-15s %-15s\n", "--------------------------------", "---------------", "---------------");
 
-    if( count > 0 )
+    // Iterate through modules
+    size_t count = 0;
+    const Dmod_ModuleInfo_t* module;
+    while( (module = Dmod_ReadModule( iterator )) != NULL )
     {
-        // Print header
-        printf("%-30s %-15s %-15s\n", "Module Name", "Version", "State");
-        printf("%-30s %-15s %-15s\n", "--------------------------------", "---------------", "---------------");
-
-        // Print each module
-        for( size_t i = 0; i < count; i++ )
+        const char* stateStr = "Unknown";
+        switch( module->State )
         {
-            const char* stateStr = "Unknown";
-            switch( modules[i].State )
-            {
-                case Dmod_ModuleState_Available:
-                    stateStr = "Available";
-                    break;
-                case Dmod_ModuleState_Loaded:
-                    stateStr = "Loaded";
-                    break;
-                case Dmod_ModuleState_Enabled:
-                    stateStr = "Enabled";
-                    break;
-                case Dmod_ModuleState_Running:
-                    stateStr = "Running";
-                    break;
-                default:
-                    stateStr = "Unknown";
-                    break;
-            }
-
-            printf("%-30s %-15s %-15s\n", 
-                   modules[i].ModuleName,
-                   modules[i].Version[0] != '\0' ? modules[i].Version : "N/A",
-                   stateStr);
+            case Dmod_ModuleState_Available:
+                stateStr = "Available";
+                break;
+            case Dmod_ModuleState_Loaded:
+                stateStr = "Loaded";
+                break;
+            case Dmod_ModuleState_Enabled:
+                stateStr = "Enabled";
+                break;
+            case Dmod_ModuleState_Running:
+                stateStr = "Running";
+                break;
+            default:
+                stateStr = "Unknown";
+                break;
         }
+
+        printf("%-30s %-15s %-15s\n", 
+               module->ModuleName,
+               module->Version[0] != '\0' ? module->Version : "N/A",
+               stateStr);
+        count++;
     }
-    else
+
+    // Close iterator
+    Dmod_CloseModules( iterator );
+
+    if( count == 0 )
     {
-        printf("No modules found. Try:\n");
+        printf("\nNo modules found. Try:\n");
         printf("  - Setting DMOD_REPO_PATHS environment variable to a directory with .dmf/.dmfc files\n");
         printf("  - Running with module name arguments: %s <module_name>\n", argv[0]);
     }
+    else
+    {
+        printf("\nTotal modules found: %zu\n", count);
+    }
 
     printf("\n");
     return 0;

inc/dmod.h

@@ -126,7 +126,9 @@ DMOD_BUILTIN_API( Dmod, 1.0, size_t     , _GetNumberOfPackages, ( void ) );
 DMOD_BUILTIN_API( Dmod, 1.0, bool       , _GetPackageInfo, ( uint32_t PackageIndex, char* outName, size_t NameMaxLength, size_t* outSize ) );
 DMOD_BUILTIN_API( Dmod, 1.0, uint32_t   , _GetMainIndexFromPackage, ( const char* PackageName ) );
 
-DMOD_BUILTIN_API( Dmod, 1.0, size_t     , _ReadModules, ( Dmod_ModuleInfo_t* outModules, size_t Max ) );
+DMOD_BUILTIN_API( Dmod, 1.0, Dmod_ModulesIterator_t, _OpenModules, ( void ) );
+DMOD_BUILTIN_API( Dmod, 1.0, const Dmod_ModuleInfo_t*, _ReadModule, ( Dmod_ModulesIterator_t Iterator ) );
+DMOD_BUILTIN_API( Dmod, 1.0, void      , _CloseModules, ( Dmod_ModulesIterator_t Iterator ) );
 
 //! @}
 

inc/dmod_types.h

@@ -27,6 +27,11 @@ typedef enum
     Dmod_ModuleType_Count,
 } Dmod_ModuleType_t;
 
+/**
+ * @brief Module state enumeration
+ * 
+ * Describes the current state of a module in the system.
+ */
 typedef enum 
 {
     Dmod_ModuleState_Available,     //!< Module is available but not loaded
@@ -37,13 +42,25 @@ typedef enum
     Dmod_ModuleState_Count,
 } Dmod_ModuleState_t;
 
+/**
+ * @brief Module information structure
+ * 
+ * Contains information about a module including its name, version, and current state.
+ */
 typedef struct 
 {
-    char                   ModuleName[DMOD_MAX_MODULE_NAME_LENGTH];
-    char                   Version[DMOD_MAX_VERSION_LENGTH];
-    Dmod_ModuleState_t     State;
+    char                   ModuleName[DMOD_MAX_MODULE_NAME_LENGTH];  //!< Name of the module
+    char                   Version[DMOD_MAX_VERSION_LENGTH];         //!< Version string of the module
+    Dmod_ModuleState_t     State;                                    //!< Current state of the module
 } Dmod_ModuleInfo_t;
 
+/**
+ * @brief Modules iterator handle
+ * 
+ * @note Opaque handle for iterating through modules. Use Dmod_OpenModules, Dmod_ReadModule, and Dmod_CloseModules.
+ */
+typedef void* Dmod_ModulesIterator_t;
+
 typedef struct 
 {
     uint32_t       Size;