From ac1fb9fa07731791a4a1cf5135953dc587fadc57 Mon Sep 17 00:00:00 2001
From: Lentil Hoffman <lentil@laddhoffman.com>
Date: Thu, 19 Jun 2025 16:53:05 -0500
Subject: [PATCH] docs: enhance JSDoc for DockerOrchestrator cleanup methods

- Add detailed documentation for `cleanup()` and `cleanupFailedStart()` methods
- Clarify the purpose, behavior, and differences between the methods
- Document parameters, return values, and error handling
- Add @remarks sections for important implementation details
---
 .../docker-orchestrator/index.ts              | 29 +++++++++++++++++--
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/src/orchestration/docker-orchestrator/index.ts b/src/orchestration/docker-orchestrator/index.ts
index 021a60c..d6f5f25 100644
--- a/src/orchestration/docker-orchestrator/index.ts
+++ b/src/orchestration/docker-orchestrator/index.ts
@@ -305,8 +305,19 @@ export class DockerOrchestrator extends BaseOrchestrator {
 
 
   /**
-   * Clean up resources if node startup fails
-   * @param nodeId ID of the node that failed to start
+   * Cleans up resources for a specific node that failed to start properly.
+   * 
+   * This method is automatically called when a node fails to start during the `startNode` process.
+   * It handles cleanup of both the container and network resources associated with the failed node,
+   * and ensures all internal state is properly cleaned up.
+   * 
+   * @remarks
+   * - Runs container and network cleanup in parallel for efficiency
+   * - Handles errors gracefully by logging them without rethrowing
+   * - Cleans up internal state for just the specified node
+   * - Used internally by the orchestrator during error handling
+   * 
+   * @param nodeId - The unique identifier of the node that failed to start
    * @private
    */
   private async cleanupFailedStart(nodeId: string): Promise<void> {
@@ -387,7 +398,19 @@ export class DockerOrchestrator extends BaseOrchestrator {
   }
 
   /**
-   * Clean up all resources
+   * Cleans up all resources managed by this orchestrator.
+   * 
+   * This method should be called during shutdown or when you need to completely tear down
+   * all containers and networks created by this orchestrator instance.
+   * 
+   * @remarks
+   * - Stops and removes all containers first
+   * - Then removes all networks (sequential execution)
+   * - Clears all internal state including node handles and log streams
+   * - Throws any errors that occur during cleanup
+   * - Should be called when the orchestrator is being shut down
+   * 
+   * @throws {Error} If any error occurs during the cleanup process
    */
   async cleanup(): Promise<void> {
     debug('Starting cleanup of all resources...');