Minor refactoring

packages/cache/src/cache.ts

@@ -106,12 +106,12 @@ export async function restoreCache(
 /**
  * Restores cache using the legacy Cache Service
  *
- * @param paths
- * @param primaryKey
- * @param restoreKeys
- * @param options
- * @param enableCrossOsArchive
- * @returns
+ * @param paths a list of file paths to restore from the cache
+ * @param primaryKey an explicit key for restoring the cache
+ * @param restoreKeys an optional ordered list of keys to use for restoring the cache if no cache hit occurred for key
+ * @param options cache download options
+ * @param enableCrossOsArchive an optional boolean enabled to restore on windows any cache created on any platform
+ * @returns string returns the key for the cache hit, otherwise returns undefined
  */
 async function restoreCacheV1(
   paths: string[],
@@ -202,7 +202,7 @@ async function restoreCacheV1(
 }
 
 /**
- * Restores cache using the new Cache Service
+ * Restores cache using Cache Service v2
  *
  * @param paths a list of file paths to restore from the cache
  * @param primaryKey an explicit key for restoring the cache
@@ -448,12 +448,12 @@ async function saveCacheV1(
 }
 
 /**
- * Save cache using the new Cache Service
+ * Save cache using Cache Service v2
  *
- * @param paths
- * @param key
- * @param options
- * @param enableCrossOsArchive
+ * @param paths a list of file paths to restore from the cache
+ * @param key an explicit key for restoring the cache
+ * @param options cache upload options
+ * @param enableCrossOsArchive an optional boolean enabled to save cache on windows which could be restored on any platform
  * @returns
  */
 async function saveCacheV2(
@@ -509,8 +509,7 @@ async function saveCacheV2(
       )
     }
 
-    // Set the archive size in the options, will be used to display the upload
-    // progress
+    // Set the archive size in the options, will be used to display the upload progress
     options.archiveSizeBytes = archiveFileSize
 
     core.debug('Reserving Cache')

packages/cache/src/internal/uploadUtils.ts

@@ -119,6 +119,16 @@ export class UploadProgress {
   }
 }
 
+/**
+ * Uploads a cache archive directly to Azure Blob Storage using the Azure SDK.
+ * This function will display progress information to the console. Concurrency of the
+ * upload is determined by the calling functions.
+ *
+ * @param signedUploadURL
+ * @param archivePath
+ * @param options
+ * @returns
+ */
 export async function uploadCacheArchiveSDK(
   signedUploadURL: string,
   archivePath: string,
@@ -151,7 +161,7 @@ export async function uploadCacheArchiveSDK(
     // TODO: better management of non-retryable errors
     if (response._response.status >= 400) {
       throw new InvalidResponseError(
-        `Upload failed with status code ${response._response.status}`
+        `uploadCacheArchiveSDK: upload failed with status code ${response._response.status}`
       )
     }