Add some JSDocs comments to types, convert some existing comments. (#2363)

* Add some JSDocs comments to types, convert some existing comments.

* Add JSDoc comments to EngineCommandManager

* Add deprecation message to `lastArtifactMap`

* fmt

* A snapshot a day keeps the bugs away! 📷🐛 (OS: ubuntu)

* A snapshot a day keeps the bugs away! 📷🐛 (OS: ubuntu)

* Rerun CI

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

src/lang/std/engineConnection.ts

@@ -54,8 +54,16 @@ interface PendingCommand extends CommandInfo {
   resolve: (val: ResolveCommand) => void
 }
 
+/**
+ * The ArtifactMap is a client-side representation of the artifacts that
+ * have been sent to the server-side engine. It is used to keep track of
+ * the state of each command, and to resolve the promise that was returned.
+ * It is also used to keep track of what entities are in the engine scene,
+ * so that we can associate IDs returned from the engine with the
+ * lines of KCL code that generated them.
+ */
 export interface ArtifactMap {
-  [key: string]: ResultCommand | PendingCommand | FailedCommand
+  [commandId: string]: ResultCommand | PendingCommand | FailedCommand
 }
 
 interface NewTrackArgs {
@@ -63,10 +71,11 @@ interface NewTrackArgs {
   mediaStream: MediaStream
 }
 
-// This looks funny, I know. This is needed because node and the browser
-// disagree as to the type. In a browser it's a number, but in node it's a
-// "Timeout".
-type Timeout = ReturnType<typeof setTimeout>
+/** This looks funny, I know. This is needed because node and the browser
+ * disagree as to the type. In a browser it's a number, but in node it's a
+ * "Timeout".
+ */
+type IsomorphicTimeout = ReturnType<typeof setTimeout>
 
 type ClientMetrics = Models['ClientMetrics_type']
 
@@ -188,9 +197,11 @@ export type EngineConnectionState =
   | State<EngineConnectionStateType.Disconnecting, DisconnectingValue>
   | State<EngineConnectionStateType.Disconnected, void>
 
-// EngineConnection encapsulates the connection(s) to the Engine
-// for the EngineCommandManager; namely, the underlying WebSocket
-// and WebRTC connections.
+/**
+ * EngineConnection encapsulates the connection(s) to the Engine
+ * for the EngineCommandManager; namely, the underlying WebSocket
+ * and WebRTC connections.
+ */
 class EngineConnection {
   websocket?: WebSocket
   pc?: RTCPeerConnection
@@ -227,23 +238,40 @@ class EngineConnection {
     this.onConnectionStateChange(this._state)
   }
 
-  private failedConnTimeout: Timeout | null
+  private failedConnTimeout: IsomorphicTimeout | null
 
   readonly url: string
   private readonly token?: string
 
-  // For now, this is only used by the NetworkHealthIndicator.
-  // We can eventually use it for more, but one step at a time.
+  /**For now, this is only used by the NetworkHealthIndicator.
+   * We can eventually use it for more, but one step at a time.
+   */
   private onConnectionStateChange: (state: EngineConnectionState) => void
 
-  // These are used for the EngineCommandManager and were created
-  // before onConnectionStateChange existed.
+  /**
+   * Used for the EngineCommandManager, created before
+   * onConnectionStateChange existed.
+   */
   private onEngineConnectionOpen: (engineConnection: EngineConnection) => void
+  /**
+   * Used for the EngineCommandManager, created before
+   * onConnectionStateChange existed.
+   */
   private onConnectionStarted: (engineConnection: EngineConnection) => void
+  /**
+   * Used for the EngineCommandManager, created before
+   * onConnectionStateChange existed.
+   */
   private onClose: (engineConnection: EngineConnection) => void
+  /**
+   * Used for the EngineCommandManager, created before
+   * onConnectionStateChange existed.
+   */
   private onNewTrack: (track: NewTrackArgs) => void
 
-  // TODO: actual type is ClientMetrics
+  /**
+   * @todo actual type is `ClientMetrics`
+   */
   public webrtcStatsCollector?: () => Promise<WebRTCClientMetrics>
   private engineCommandManager: EngineCommandManager
 
@@ -322,11 +350,13 @@ class EngineConnection {
     }
   }
 
-  // connect will attempt to connect to the Engine over a WebSocket, and
-  // establish the WebRTC connections.
-  //
-  // This will attempt the full handshake, and retry if the connection
-  // did not establish.
+  /**
+   * Attempts to connect to the Engine over a WebSocket, and
+   * establish the WebRTC connections.
+   *
+   * This will attempt the full handshake, and retry if the connection
+   * did not establish.
+   */
   connect() {
     if (this.isConnecting() || this.isReady()) {
       return
@@ -908,21 +938,66 @@ export type CommandLog =
       data: null
     }
 
+/**
+ * The EngineCommandManager is the main interface to the Engine for Modeling App.
+ *
+ * It is responsible for sending commands to the Engine, and managing the state
+ * of those commands. It also sets up and tears down the connection to the Engine
+ * through the {@link EngineConnection} class.
+ *
+ * It also maintains an {@link artifactMap} that keeps track of the state of each
+ * command, and the artifacts that have been generated by those commands.
+ */
 export class EngineCommandManager {
+  /**
+   * The artifactMap is a client-side representation of the commands that have been sent
+   * to the server-side geometry engine, and the state of their resulting artifacts.
+   *
+   * It is used to keep track of the state of each command, which can fail, succeed, or be
+   * pending.
+   *
+   * It is also used to keep track of our client's understanding of what is in the engine scene
+   * so that we can map to and from KCL code. Each artifact maintains a source range to the part
+   * of the KCL code that generated it.
+   */
   artifactMap: ArtifactMap = {}
+  /**
+   * The {@link ArtifactMap} from the previous engine connection. This is used as a fallback
+   * when the engine connection is reset without a full client-side refresh.
+   *
+   * @deprecated This was used during a short time when we were choosing to not execute the engine in certain cases.
+   */
   lastArtifactMap: ArtifactMap = {}
+  /**
+   * The client-side representation of the scene command artifacts that have been sent to the server;
+   * that is, the *non-modeling* commands and corresponding artifacts.
+   *
+   * For modeling commands, see {@link artifactMap}.
+   */
   sceneCommandArtifacts: ArtifactMap = {}
+  /**
+   * A counter that is incremented with each command sent over the *unreliable* channel to the engine.
+   * This is compared to the latest received {@link inSequence} number to determine if we should ignore
+   * any out-of-order late responses in the unreliable channel.
+   */
   outSequence = 1
+  /**
+   * The latest sequence number received from the engine over the *unreliable* channel.
+   * This is compared to the {@link outSequence} number to determine if we should ignore
+   * any out-of-order late responses in the unreliable channel.
+   */
   inSequence = 1
   pool?: string
   engineConnection?: EngineConnection
   defaultPlanes: DefaultPlanes | null = null
   commandLogs: CommandLog[] = []
   _commandLogCallBack: (command: CommandLog[]) => void = () => {}
-  // Folks should realize that wait for ready does not get called _everytime_
-  // the connection resets and restarts, it only gets called the first time.
-  // Be careful what you put here.
   private resolveReady = () => {}
+  /** Folks should realize that wait for ready does not get called _everytime_
+   *  the connection resets and restarts, it only gets called the first time.
+   *
+   *  Be careful what you put here.
+   */
   waitForReady: Promise<void> = new Promise((resolve) => {
     this.resolveReady = resolve
   })