chore: improvements to provider docs (#11451)

packages/core/types/src/file/provider.ts

@@ -5,11 +5,17 @@
  */
 export type ProviderFileResultDTO = {
   /**
-   * The file's URL.
+   * The file's URL that users or systems
+   * can use to access the file.
    */
   url: string
   /**
-   * The file's key.
+   * The file's key allowing you to later
+   * identify the file in the third-party
+   * system. For example, the S3 Module Provider
+   * returns the file's key in S3, whereas the
+   * Local File Module Provider returns the file's
+   * path.
    */
   key: string
 }
@@ -21,7 +27,7 @@ export type ProviderFileResultDTO = {
  */
 export type ProviderGetFileDTO = {
   /**
-   * The file's key.
+   * The file's key as returned during upload.
    */
   fileKey: string
   [x: string]: unknown

packages/core/utils/src/file/abstract-file-provider.ts

@@ -90,9 +90,13 @@ export class AbstractFileProviderService implements IFileProvider {
   }
 
   /**
-   * This method uploads a file using your provider's custom logic.
+   * This method uploads a file using your provider's custom logic. In this method, you can upload the file
+   * into your provider's storage, and return the uploaded file's details.
+   * 
+   * This method will be used when uploading product images, CSV files for imports, or other
+   * custom file uploads.
    *
-   * @param {FileTypes.ProviderUploadFileDTO} file - The file to upload
+   * @param {FileTypes.ProviderUploadFileDTO} file - The file to upload.
    * @returns {Promise<FileTypes.ProviderFileResultDTO>} The uploaded file's details.
    *
    * @example
@@ -103,10 +107,12 @@ export class AbstractFileProviderService implements IFileProvider {
    *   ): Promise<ProviderFileResultDTO> {
    *     // TODO upload file to third-party provider
    *     // or using custom logic
+   *     // for example:
+   *     this.client.upload(file)
    *
    *     return {
    *       url: "some-url.com",
-   *       key: "file-name"
+   *       key: "file-name-or-id"
    *     }
    *   }
    * }
@@ -118,7 +124,8 @@ export class AbstractFileProviderService implements IFileProvider {
   }
 
   /**
-   * This method deletes the file from storage.
+   * This method deletes the file from storage. It's used when an admin user deletes a product image,
+   * or other custom file deletions.
    *
    * @param {FileTypes.ProviderDeleteFileDTO} file - The details of the file to delete.
    * @returns {Promise<void>} Resolves when the file is deleted.