vscode: add docs to installation module interfaces and sanity check to donloadFile()

editors/code/src/installation/download_file.ts

@@ -1,17 +1,25 @@
 import fetch from "node-fetch";
 import { throttle } from "throttle-debounce";
 import * as fs from "fs";
+import { strict as assert } from "assert";
 
+/**
+ * Downloads file from `url` and stores it at `destFilePath`.
+ * `onProgress` callback is periodically called to track the progress of downloading,
+ * it gets the already read and total amount of bytes to read as its parameters.
+ */
 export async function downloadFile(
     url: string,
     destFilePath: fs.PathLike,
     onProgress: (readBytes: number, totalBytes: number) => void
 ): Promise<void> {
-    onProgress = throttle(1000, /* noTrailing: */ true, onProgress);
+    onProgress = throttle(500, /* noTrailing: */ true, onProgress);
 
     const response = await fetch(url);
 
     const totalBytes = Number(response.headers.get('content-length'));
+    assert(!Number.isNaN(totalBytes), "Sanity check of content-length protocol");
+
     let readBytes = 0;
 
     return new Promise<void>((resolve, reject) => response.body

editors/code/src/installation/interfaces.ts

@@ -3,24 +3,51 @@ export interface GithubRepo {
     owner: string;
 }
 
+/**
+ * Metadata about particular artifact retrieved from GitHub releases.
+ */
 export interface ArtifactMetadata {
     releaseName: string;
     downloadUrl: string;
 }
 
-
+/**
+ * Type tag for `BinarySource` discriminated union.
+ */
 export enum BinarySourceType { ExplicitPath, GithubBinary }
 
-export type BinarySource = EplicitPathSource | GithubBinarySource;
+/**
+ * Represents the source of a binary artifact which is either specified by the user
+ * explicitly, or bundled by this extension from GitHub releases.
+ */
+export type BinarySource = ExplicitPathSource | GithubBinarySource;
 
-export interface EplicitPathSource {
+
+export interface ExplicitPathSource {
     type: BinarySourceType.ExplicitPath;
+
+    /**
+     * Filesystem path to the binary specified by the user explicitly.
+     */
     path: string;
 }
 
 export interface GithubBinarySource {
     type: BinarySourceType.GithubBinary;
+
+    /**
+     * Repository where the binary is stored.
+     */
     repo: GithubRepo;
+
+    /**
+     * Directory on the filesystem where the bundled binary is stored.
+     */
     dir: string;
+
+    /**
+     * Name of the binary file. It is stored under the same name on GitHub releases
+     * and in local `.dir`.
+     */
     file: string;
 }