Document & rename spec class to be better

Author: yuvipanda

binderhub/static/js/components/BuilderLauncher.jsx

@@ -64,11 +64,7 @@ async function buildImage(
       case "ready": {
         setProgressState(PROGRESS_STATES.SUCCESS);
         image.close();
-        redirectToRunningServer(
-          data.url,
-          data.token,
-          spec.runtimeParams.urlPath,
-        );
+        redirectToRunningServer(data.url, data.token, spec.launchSpec.urlPath);
         console.log(data);
         break;
       }

binderhub/static/js/pages/HomePage.jsx

@@ -3,7 +3,7 @@ import { BuilderLauncher } from "../components/BuilderLauncher.jsx";
 import { HowItWorks } from "../components/HowItWorks.jsx";
 import { useEffect, useState } from "react";
 import { FaviconUpdater } from "../components/FaviconUpdater.jsx";
-import { Spec, RuntimeParams } from "../spec.js";
+import { Spec, LaunchSpec } from "../spec.js";
 
 /**
  * @typedef {object} HomePageProps

binderhub/static/js/pages/LoadingPage.jsx

@@ -5,7 +5,7 @@ import { useSearchParams } from "react-router-dom";
 import { NBViewerIFrame } from "../components/NBViewerIFrame.jsx";
 import { LoadingIndicator } from "../components/LoadingIndicator.jsx";
 import { FaviconUpdater } from "../components/FaviconUpdater.jsx";
-import { RuntimeParams, Spec } from "../spec.js";
+import { LaunchSpec, Spec } from "../spec.js";
 
 /**
  * @typedef {object} LoadingPageProps
@@ -23,10 +23,7 @@ export function LoadingPage({ baseUrl }) {
 
   const [isLaunching, setIsLaunching] = useState(false);
 
-  const spec = new Spec(
-    buildSpec,
-    RuntimeParams.fromSearchParams(searchParams),
-  );
+  const spec = new Spec(buildSpec, LaunchSpec.fromSearchParams(searchParams));
 
   useEffect(() => {
     // Start launching after the DOM has fully loaded

binderhub/static/js/spec.js

@@ -1,7 +1,7 @@
-export class RuntimeParams {
+export class LaunchSpec {
   /**
    *
-   * @param {string} urlPath
+   * @param {string} urlPath Path inside the Jupyter server to redirect the user to after launching
    */
   constructor(urlPath) {
     this.urlPath = urlPath;
@@ -10,10 +10,13 @@ export class RuntimeParams {
   }
 
   /**
+   * Create a LaunchSpec from given query parameters in the URL
+   *
+   * Handles backwards compatible parameters as needed.
    *
    * @param {URLSearchParams} searchParams
    *
-   * @returns {RuntimeParams}
+   * @returns {LaunchSpec}
    */
   static fromSearchParams(searchParams) {
     let urlPath = searchParams.get("urlpath");
@@ -33,17 +36,23 @@ export class RuntimeParams {
       urlPath = `tree/${encodeURI(filePath)}`;
     }
 
-    return new RuntimeParams(urlPath);
+    return new LaunchSpec(urlPath);
   }
 }
 
+/**
+ * A full binder specification
+ *
+ * Includes a *build* specification (determining what is built), and a
+ * *launch* specification (determining what is launched).
+ */
 export class Spec {
   /**
-   * @param {string} buildSpec
-   * @param {RuntimeParams} runtimeParams
+   * @param {string} buildSpec Build specification, passed directly to binderhub API
+   * @param {LaunchSpec} launchSpec Launch specification, determining what is launched
    */
-  constructor(buildSpec, runtimeParams) {
+  constructor(buildSpec, launchSpec) {
     this.buildSpec = buildSpec;
-    this.runtimeParams = runtimeParams;
+    this.launchSpec = launchSpec;
   }
 }