Improve block comment for Plugin::fetchIndirection()

Changed:
- Rewrite the summary of the method.
- Add a description of packages with an intermediary.
- Improve formatting, description, and example of `indirection` settings.

src/Plugin.php

@@ -186,14 +186,49 @@ public function handlePreInstallUpdateEvent(PackageEvent $event): void
     }
 
     /**
-     * Handle indirection process, like used by WP EDD
+     * Handle indirect package download URL.
      *
-     * The "indirection" property can contain:
-     * "http" and "ssl" object, as defined by https://github.com/composer/composer/blob/main/src/Composer/Util/Http/CurlDownloader.php
-     * "parse": {
-     *   "format": "json" # only supported value
-     *   "key": # A string (or an object for specifying nested keys to fetch the package download URL from
+     * For example, certain WordPress plugins such as Gravity Forms,
+     * and managers such Easy Digital Downloads (EDD),
+     * usually serve their downloads from a temporary signed URL
+     * that is provided through an intermediary URL.
+     *
+     * The `indirection` property can contain:
+     *
+     * * `http` and `ssl` objects, as defined by
+     *   {@link https://github.com/composer/composer/blob/2.2/src/Composer/Util/Http/CurlDownloader.php `\Composer\Util\Http\CurlDownloader`},
+     *   to customize the request to the intermediary URL.
+     * * `parse` object which expects:
+     *   * `format`: A string indicating the kind of response expected from the intermediary's
+     *     HTTP response. Only `json` is supported.
+     *   * `key`: A string, or an object for specifying nested keys, to extract
+     *     the package download URL from.
+     *
+     * Example:
+     *
+     * ```jsonc
+     * "extra": {
+     *     "private-composer-installer": {
+     *         "indirection": {
+     *             "http": {
+     *                 "method": "POST"
+     *             },
+     *             "ssl": {
+     *                 "passphrase": "****"
+     *             },
+     *             "parse": {
+     *                 "format": "json",
+     *                 "key": "download_url"
+     *             }
+     *         }
+     *     }
      * }
+     * ```
+     *
+     * @param  string  $url   The package intermediary URL.
+     * @param  mixed[] $extra The package extra data.
+     * @return string Returns the package download URL on sucess or
+     *     the serialized response from the intermediary on failure.
      */
     public function fetchIndirection(PreFileDownloadEvent $event, string $url, array $extra): string
     {