doc(LayerUpdateState): update and refine documentation

Author: Desplandis

packages/Main/src/Layer/LayerUpdateState.ts

@@ -42,10 +42,19 @@ class LayerUpdateState {
         };
     }
 
+    /**
+     * Checks if the update has finished successfully.
+     */
     hasFinished() {
         return UPDATE_STATE.FINISHED == this.state;
     }
 
+    /**
+     * Checks if an update can be attempted based on the current update state.
+     *
+     * @param timestamp - Current timestamp in milliseconds (defaults to
+     * Date.now()).
+     */
     canTryUpdate(timestamp = Date.now()) {
         switch (this.state) {
             case UPDATE_STATE.IDLE: {
@@ -64,6 +73,9 @@ class LayerUpdateState {
         }
     }
 
+    /**
+     * Gives the number of seconds to wait before the next retry attempt.
+     */
     secondsUntilNextTry() {
         if (this.state !== UPDATE_STATE.ERROR) {
             return 0;
@@ -74,19 +86,36 @@ class LayerUpdateState {
         return PAUSE_BETWEEN_ERRORS[idx];
     }
 
+    /**
+     * Marks the beginning of a new update attempt.
+     */
     newTry() {
         this.state = UPDATE_STATE.PENDING;
     }
 
+    /**
+     * Marks the update as successful. It resets the error tracking.
+     */
     success() {
         this.lastErrorTimestamp = 0;
         this.state = UPDATE_STATE.IDLE;
     }
 
+    /**
+     * Marks the update as permanently finished, preventing further update
+     * attempts.
+     */
     noMoreUpdatePossible() {
         this.state = UPDATE_STATE.FINISHED;
     }
 
+    /**
+     * Handles the case where no data is available for the requested level.
+     * Updates the lowest level error tracking for future retry attempts.
+     *
+     * @param failureParams - The current context of the failure (this includes
+     * the current updated level).
+     */
     noData(failureParams: { targetLevel: number }) {
         this.state = UPDATE_STATE.IDLE;
         this.failureParams.lowestLevelError = Math.min(
@@ -95,6 +124,15 @@ class LayerUpdateState {
         );
     }
 
+    /**
+     * Handles update failures. An error is either definitive or retryable (up
+     * to four attempts).
+     *
+     * @param timestamp - The timestamp when the failure occurred.
+     * @param definitive - Whether this error stops the update process.
+     * @param failureParams - The current context of the failure (this includes
+     * the current updated level).
+     */
     failure(timestamp: number, definitive: boolean, failureParams: { targetLevel: number }) {
         if (failureParams && failureParams.targetLevel != undefined) {
             this.failureParams.lowestLevelError = Math.min(
@@ -107,6 +145,9 @@ class LayerUpdateState {
         this.errorCount++;
     }
 
+    /**
+     * Checks if the layer is currently in an error state.
+     */
     inError() {
         return this.state == UPDATE_STATE.DEFINITIVE_ERROR || this.state == UPDATE_STATE.ERROR;
     }