chore(storage): add clear documentation to storage apis (#11982)

chore(storage): add clear documentation to storage apis --------- Co-authored-by: AllanZhengYP <[email protected]>
aws-amplify · Sep 7, 2023 · d3bde7b · d3bde7b
1 parent 2af0ca0
commit d3bde7b
Show file tree

Hide file tree

Showing 3 changed files with 10 additions and 7 deletions.
diff --git a/packages/storage/src/providers/s3/apis/getUrl.ts b/packages/storage/src/providers/s3/apis/getUrl.ts
@@ -7,16 +7,19 @@ import { S3GetUrlOptions, S3GetUrlResult } from '../types';
 import { getUrl as getUrlInternal } from './internal/getUrl';
 
 /**
- * Get Presigned url of the object
+ * Get a temporary presigned URL to download the specified S3 object.
+ * The presigned URL expires when the associated role used to sign the request expires or
+ * the option  `expiresIn` is reached. The `expiresAt` property in the output object indicates when the URL MAY expire.
+ * By default, it will not validate the object that exists in S3. If you set the `options.validateObjectExistence`
+ * to true, this method will verify the given object already exists in S3 before returning a presigned
+ * URL, and will throw {@link StorageError} if the object does not exist.
  *
  * @param {StorageDownloadDataRequest<S3GetUrlOptions>} The request object
  * @return {Promise<S3GetUrlResult>} url of the object
  * @throws service: {@link S3Exception} - thrown when checking for existence of the object
  * @throws validation: {@link StorageValidationErrorCode } - Validation errors
  * thrown either username or key are not defined.
  *
- * TODO: add config errors
- *
  */
 export const getUrl = (
 	req: StorageDownloadDataRequest<S3GetUrlOptions>

diff --git a/packages/storage/src/providers/s3/apis/list.ts b/packages/storage/src/providers/s3/apis/list.ts
@@ -12,18 +12,18 @@ import { list as listInternal } from './internal/list';
 
 type S3ListApi = {
 	/**
-	 * Lists bucket objects with pagination.
+	 * List files with given prefix in pages
+	 * pageSize defaulted to 1000. Additionally, the result will include a nextToken if there are more items to retrieve.
 	 * @param {StorageListRequest<StorageListPaginateOptions>} req - The request object
 	 * @return {Promise<S3ListPaginateResult>} - Promise resolves to list of keys and metadata with
-	 * pageSize defaulting to 1000. Additionally the result will include a nextToken if there are more items to retrieve
 	 * @throws service: {@link S3Exception} - S3 service errors thrown when checking for existence of bucket
 	 * @throws validation: {@link StorageValidationErrorCode } - thrown when there are issues with credentials
 	 */
 	(
 		req?: StorageListRequest<StorageListPaginateOptions>
 	): Promise<S3ListPaginateResult>;
 	/**
-	 * Lists all bucket objects.
+	 * List all files from S3. You can set `listAll` to true in `options` to get all the files from S3.
 	 * @param {StorageListRequest<StorageListAllOptions>} req - The request object
 	 * @return {Promise<S3ListAllResult>} - Promise resolves to list of keys and metadata for all objects in path
 	 * @throws service: {@link S3Exception} - S3 service errors thrown when checking for existence of bucket

diff --git a/packages/storage/src/providers/s3/apis/remove.ts b/packages/storage/src/providers/s3/apis/remove.ts
@@ -10,7 +10,7 @@ import {
 import { remove as removeInternal } from './internal/remove';
 
 /**
- * Remove the object that is specified by the `req`.
+ * Remove a file from your S3 bucket.
  * @param {StorageOperationRequest<StorageRemoveOptions>} req - The request object
  * @return {Promise<StorageRemoveResult>} - Promise resolves upon successful removal of the object
  * @throws service: {@link S3Exception} - S3 service errors thrown while getting properties