docs: address more suggestions, improve comments

scripts/cluster-scanner/README.md

@@ -12,22 +12,22 @@ The **Cluster Scanner** tool uses the Palette Go SDK to scan your Palette enviro
 
 ## Usage
 
-1. Open a terminal window and export your Palette URL. Replace `<your-palette-url>` with your Palette URL, for example, `console.spectrocloud.com`.
+1. Open a terminal window and export your Palette URL. Substitute `<REPLACE_ME>` with your Palette URL, for example, `console.spectrocloud.com`.
 
    ```shell
-   export PALETTE_HOST=<your-palette-url>
+   export PALETTE_HOST=<REPLACE_ME>
    ```
 
-2. Export your Palette API key. Replace `<your-palette-api-key>` with your Palette API key.
+2. Export your Palette API key. Replace `<REPLACE_ME>` with your Palette API key.
 
    ```shell
-   export PALETTE_API_KEY=<your-palette-api-key>
+   export PALETTE_API_KEY=<REPLACE_ME>
    ```
 
-3. To scan a specific project, export the project's UID. Replace `<your-palette-project>` with the Palette project UID. If no project is provided, the tool assumes a tenant scope and scans clusters across all projects.
+3. To scan a specific project, export the project's UID. Substitute `<REPLACE_ME>` with the Palette project UID. If no project is provided, the tool assumes a tenant scope and scans clusters across all projects.
 
    ```shell
-   export PALETTE_PROJECT_UID=<your-palette-project>
+   export PALETTE_PROJECT_UID=<REPLACE_ME>
    ```
 
 4. Navigate to the `cluster-scanner` folder.

scripts/cluster-scanner/internal/format_age.go

@@ -5,7 +5,7 @@ import (
 	"time"
 )
 
-// Format the cluster age using weeks, days, and hours
+// FormatAge returns the age of a cluster as the number of weeks, days, and hours.
 func FormatAge (clusterAge time.Duration) (int, int, int) {
     const hoursPerWeek int = 168
     weeks := int(clusterAge.Hours()) / hoursPerWeek
@@ -15,7 +15,9 @@ func FormatAge (clusterAge time.Duration) (int, int, int) {
     return  weeks, days, hours
 }
 
-// Return the cluster age as a formatted string
+// PrintFormattedAge returns a formatted string representation of the cluster's age.
+// It uses FormatAge to calculate the age in weeks, days, and hours and formats
+// the output accordingly.
 func PrintFormattedAge (clusterAge time.Duration) (string) {
     weeks, days, hours := FormatAge(clusterAge)
     var formattedString string

scripts/cluster-scanner/internal/search_clusters.go

@@ -1,15 +1,12 @@
 package internal
 
 import (
-	"log/slog"
-
 	"github.com/spectrocloud/palette-sdk-go/api/models"
 	"github.com/spectrocloud/palette-sdk-go/client"
 )
 
-func SearchClusters (paletteClient *client.V1Client, logger *slog.Logger) ([]*models.V1SpectroClusterSummary, error) {
-	// Search for clusters
-	logger.Info("Searching for clusters...")
+// SearchClusters retrieves a list of cluster summaries from the Palette client.
+func SearchClusters (paletteClient *client.V1Client) ([]*models.V1SpectroClusterSummary, error) {
+	// Search for clusters using the provided Palette client with default filters and sorting.
 	return paletteClient.SearchClusterSummaries(&models.V1SearchFilterSpec{}, []*models.V1SearchFilterSortSpec{})
-
 }

scripts/cluster-scanner/internal/search_old_clusters.go

@@ -8,19 +8,22 @@ import (
 	"github.com/spectrocloud/palette-sdk-go/api/models"
 )
 
+// SearchOldClusters checks for clusters that have been running for more than 24 hours.
+// It returns a boolean indicating if any old clusters were found and a message
+// with the clusters' information.
 func SearchOldClusters (clusters []*models.V1SpectroClusterSummary, logger *slog.Logger) (bool, string) {
-	// Variable to keep track of any found clusters older than 24h
+	// Variable to keep track of any found clusters older than 24 hours
 	foundOldCluster := false
+	var message string
 
-	// List the clusters that are running for more than 24h
+	// Iterate through the clusters to find those running for more than 24 hours
 	for _, cluster := range clusters {
 		timeValue := time.Time(cluster.Metadata.CreationTimestamp)
 		clusterAge := time.Now().Sub(timeValue)
 
 		if clusterAge.Hours() >= 24 {
 			foundOldCluster = true
-			message := fmt.Sprintf("The %s cluster named %s has been running for %s. Are you sure you need this cluster?", cluster.SpecSummary.CloudConfig.CloudType, cluster.Metadata.Name, PrintFormattedAge(clusterAge))
-			logger.Info(message)
+			message = fmt.Sprintf("The %s cluster named %s has been running for %s. Are you sure you need this cluster?", cluster.SpecSummary.CloudConfig.CloudType, cluster.Metadata.Name, PrintFormattedAge(clusterAge))
 		} 
 	}
 

scripts/cluster-scanner/main.go

@@ -10,25 +10,27 @@ import (
 
 func main() {
 
-    // Read environment variables
+    // Read environment variables required to initialize the Palette client
     host := os.Getenv("PALETTE_HOST")
     apiKey := os.Getenv("PALETTE_API_KEY")
     projectUid := os.Getenv("PALETTE_PROJECT_UID")
 
+    // Initialize a logger for structured output
     logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
 
-
+    // Ensure the required environment variables are provided
     if host == "" || apiKey == "" {
         logger.Error("You must specify the PALETTE_HOST and PALETTE_API_KEY environment variables.")
         os.Exit(1)
     }
 
-    // Initialize a Palette client
+    // Initialize a Palette client with the provided host and API key
     paletteClient := client.New(
         client.WithPaletteURI(host),
         client.WithAPIKey(apiKey),
     )
 
+    // Set the scope for the client based on wether the project UID is provided
     if projectUid != "" {
         client.WithScopeProject(projectUid)(paletteClient)
         logger.Info("Setting scope to project.")
@@ -37,20 +39,25 @@ func main() {
         logger.Info("Setting scope to tenant.")
     }
 
-    // Search for clusters
-    clusters, err := internal.SearchClusters(paletteClient, logger)
+    // Search for clusters using the Palette client and the SearchClusters function
+    logger.Info("Searching for clusters...")
+    clusters, err := internal.SearchClusters(paletteClient)
     if err != nil {
         logger.Error("Failed to search cluster summaries", "error", err)
 		os.Exit(2)
 	}
 
-    // Check active clusters
+    // Check if any clusters were found
 	if len(clusters) == 0 {
 		logger.Warn("There are no clusters running.")
 		return
 	}
 
-    foundOldCluster := internal.SearchOldClusters(clusters, logger)
+    // Check for clusters running for more than 24 hours using the SearchOldClusters function
+    foundOldCluster, message := internal.SearchOldClusters(clusters, logger)
+    if message != "" {
+        logger.Info(message)
+    }
 
     if !foundOldCluster {
         logger.Info("There are no clusters running for more than 24 hours.")