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.

www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/fulfillment-provider.ts

@@ -22,6 +22,12 @@ const fulfillmentProviderOptions: FormattingOptionsType = {
       reflection_typeParameters: false,
     },
     startSections: [
+      `## Understanding Fulfillment Provider Implementation
+
+The Fulfillment Module Provider handles processing fulfillments and shipments with a third-party provirder. However, it's not responsible for managing fulfillment concepts within Medusa, such as creating a fulfillment or its shipments. The Fulfillment Module uses your fulfillment provider within core operations.
+
+For example, when the merchant creates a fulfillment for an order, the Fulfillment Module uses your fulfillment provider to create the fulfillment in the third-party system, then creates the fulfillment in Medusa. So, you only have to implement the third-party fulfillment processing logic in your fulfillment provider.
+`,
       `## 1. Create Module Provider Directory
 
 Start by creating a new directory for your module provider.

www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/payment-provider.ts

@@ -22,6 +22,12 @@ const paymentProviderOptions: FormattingOptionsType = {
       reflection_typeParameters: false,
     },
     startSections: [
+      `## Understanding Payment Provider Implementation
+
+The Payment Module Provider handles processing payment with a third-party provirder. However, it's not responsible for managing payment concepts within Medusa, such as payment sessions or collections. These concepts are handled by the Payment Module which uses your payment provider within core operations.
+
+For example, when the merchant captures an order's payment, the Payment Module uses the payment provider to capture the payment, the makes updates to the \`Payment\` record associated with the order. So, you only have to implement the third-party payment processing logic in your payment provider.
+`,
       `## 1. Create Module Provider Directory
 
 Start by creating a new directory for your module provider.