From c399359c78a6cc6505a479e62a02f2db5a13fbbe Mon Sep 17 00:00:00 2001
From: Paul Berberian <pea.berberian@gmail.com>
Date: Wed, 8 Feb 2023 17:09:42 +0100
Subject: [PATCH] Update documentation for the SegmentFetchers code

---
 src/core/fetchers/cdn_prioritizer.ts         | 27 +++++++++++++-------
 src/core/fetchers/segment/segment_fetcher.ts | 27 ++++++++++++++++----
 2 files changed, 40 insertions(+), 14 deletions(-)

diff --git a/src/core/fetchers/cdn_prioritizer.ts b/src/core/fetchers/cdn_prioritizer.ts
index 78eedb164d..bb118d36b7 100644
--- a/src/core/fetchers/cdn_prioritizer.ts
+++ b/src/core/fetchers/cdn_prioritizer.ts
@@ -16,19 +16,22 @@
 
 import config from "../../config";
 import { ICdnMetadata } from "../../parsers/manifest";
-import { IPlayerError } from "../../public_types";
 import arrayFindIndex from "../../utils/array_find_index";
 import EventEmitter from "../../utils/event_emitter";
 import { CancellationSignal } from "../../utils/task_canceller";
 
 /**
- * Class signaling the priority between multiple CDN available for any given
- * resource.
+ * Class storing and signaling the priority between multiple CDN available for
+ * any given resource.
  *
- * This class might perform requests and schedule timeouts by itself to keep its
- * internal list of CDN priority up-to-date.
- * When it is not needed anymore, you should call the `dispose` method to clear
- * all resources.
+ * This class was first created to implement the complexities behind
+ * Content Steering features, though its handling hasn't been added yet as we
+ * wait for its specification to be both standardized and relied on in the wild.
+ * In the meantime, it acts as an abstraction for the simple concept of
+ * avoiding to request a CDN for any segment when an issue is encountered with
+ * one (e.g. HTTP 500 statuses) and several CDN exist for a given resource. It
+ * should be noted that this is also one of the planified features of the
+ * Content Steering specification.
  *
  * @class CdnPrioritizer
  */
@@ -41,7 +44,7 @@ export default class CdnPrioritizer extends EventEmitter<ICdnPrioritizerEvents>
   private _downgradedCdnList : {
     /**
      * Metadata of downgraded CDN, sorted by the time at which they have
-     * been downgraded.
+     * been downgraded ascending.
      */
     metadata : ICdnMetadata[];
     /**
@@ -174,8 +177,14 @@ export default class CdnPrioritizer extends EventEmitter<ICdnPrioritizerEvents>
   }
 }
 
+/** Events sent by a `CdnPrioritizer` */
 export interface ICdnPrioritizerEvents {
-  warnings : IPlayerError[];
+  /**
+   * The priority of one or several CDN changed.
+   *
+   * You might want to re-check if a CDN should still be used when this event
+   * is triggered.
+   */
   priorityChange : null;
 }
 
diff --git a/src/core/fetchers/segment/segment_fetcher.ts b/src/core/fetchers/segment/segment_fetcher.ts
index 45c4097973..956081e015 100644
--- a/src/core/fetchers/segment/segment_fetcher.ts
+++ b/src/core/fetchers/segment/segment_fetcher.ts
@@ -64,10 +64,22 @@ const generateRequestID = idGenerator();
  * An `ISegmentFetcher` also implements a retry mechanism, based on the given
  * `options` argument, which may retry a segment request when it fails.
  *
- * @param {string} bufferType
- * @param {Object} pipeline
- * @param {Object} lifecycleCallbacks
- * @param {Object} options
+ * @param {string} bufferType - Type of  buffer concerned (e.g. `"audio"`,
+ * `"video"`, `"text" etc.)
+ * @param {Object} pipeline - The transport-specific logic allowing to load
+ * segments of the given buffer type and transport protocol (e.g. DASH).
+ * @param {Object|null} cdnPrioritizer - Abstraction allowing to synchronize,
+ * update and keep track of the priorization of the CDN to use to load any given
+ * segment, in cases where multiple ones are available.
+ *
+ * Can be set to `null` in which case a minimal priorization logic will be used
+ * instead.
+ * @param {Object} lifecycleCallbacks - Callbacks that can be registered to be
+ * informed when new requests are made, ended, new metrics are available etc.
+ * This should be mainly useful to implement an adaptive logic relying on those
+ * metrics and events.
+ * @param {Object} options - Various tweaking options allowing to configure the
+ * behavior of the returned `ISegmentFetcher`.
  * @returns {Function}
  */
 export default function createSegmentFetcher<TLoadedFormat, TSegmentDataType>(
@@ -360,11 +372,16 @@ export interface ISegmentFetcherCallbacks<TSegmentDataType> {
   /**
    * Callback called when all decodable chunks of the loaded segment have been
    * communicated through the `onChunk` callback.
+   *
+   * This callback is called before the corresponding `ISegmentFetcher`'s
+   * returned Promise is resolved.
    */
   onAllChunksReceived() : void;
 
   /**
-   * Callback called when the segment request has to restart from scratch. */
+   * Callback called when the segment request has to restart from scratch, e.g.
+   * due to a request error.
+   */
   onRetry(error : IPlayerError) : void;
 }