JS: Add more inline documentation comments

binderhub/static/js/src/badge.js

@@ -1,3 +1,12 @@
+/**
+ * Generate markdown that people can put on their README or documentation to link to this binder
+ *
+ * @param {string} badgeBaseUrl Optional base URL to use for badge images. If not passed, current origin + baseUrl is used
+ * @param {string} baseUrl Base URL of this binderhub installation. Used only if badgeBaseUrl is not passed
+ * @param {string} url Link target URL that represents this binder installation
+ * @param {string} syntax Kind of markup to generate. Supports 'markdown' and 'rst'
+ * @returns {string}
+ */
 export function makeBadgeMarkup(badgeBaseUrl, baseUrl, url, syntax) {
   let badgeImageUrl;
 

binderhub/static/js/src/constants.js

@@ -1,2 +1,13 @@
+/**
+ * @type {string}
+ * Base URL of this binderhub installation
+ */
 export const BASE_URL = $("#base-url").data().url;
+
+/**
+ * @type {string}
+ * Optional base URL to use for both badge images as well as launch links.
+ *
+ * Is different from BASE_URL primarily when used as part of a federation.
+ */
 export const BADGE_BASE_URL = $("#badge-base-url").data().url;

binderhub/static/js/src/form.js

@@ -1,5 +1,15 @@
 import { getPathType } from "./path";
 
+/**
+ * Parse current values in form and return them with appropriate URL encoding
+ * @typedef FormValues
+ * @prop {string} providerPrefix prefix denoting what provider was selected
+ * @prop {string} repo repo to build
+ * @prop {[string]} ref optional ref in this repo to build
+ * @prop {string} path Path to launch after this repo has been built
+ * @prop {string} pathType Type of thing to open path with (raw url, notebook file, lab, etc)
+ * @returns {}
+ */
 export function getBuildFormValues() {
   const providerPrefix = $("#provider_prefix").val().trim();
   let repo = $("#repository").val().trim();

binderhub/static/js/src/loading.js

@@ -1,4 +1,6 @@
-// Cycle through helpful messages on the loading page
+/**
+ * List of help messages we will cycle through randomly in the loading page
+ */
 const help_messages = [
   'New to Binder? Check out the <a target="_blank" href="https://mybinder.readthedocs.io/en/latest/">Binder Documentation</a> for more information.',
   'You can learn more about building your own Binder repositories in <a target="_blank" href="https://docs.mybinder.org">the Binder community documentation</a>.',
@@ -15,7 +17,9 @@ const help_messages = [
   'Read our <a target="_blank" href="https://discourse.jupyter.org/t/how-to-reduce-mybinder-org-repository-startup-time/4956">advice for speeding up your Binder launch</a>.',
 ];
 
-// Set a launch timeout beyond-which we'll stop cycling messages
+/**
+ * Display a randomly picked help message in the loading page
+ */
 export function nextHelpText() {
   const text = $("div#loader-links p.text-center");
   let msg;

binderhub/static/js/src/log.js

@@ -1,6 +1,11 @@
 import { Terminal } from "xterm";
 import { FitAddon } from "xterm-addon-fit";
 
+/**
+ * Set up a read only xterm.js based terminal, augmented with some additional methods, to display log lines
+ *
+ * @returns Array of the xterm.js instance to write to, and a FitAddon instance to use for resizing the xterm appropriately
+ */
 export function setUpLog() {
   const log = new Terminal({
     convertEol: true,
@@ -19,16 +24,26 @@ export function setUpLog() {
   });
 
   const $panelBody = $("div.panel-body");
+
+  /**
+   * Show the log terminal
+   */
   log.show = function () {
     $("#toggle-logs button.toggle").text("hide");
     $panelBody.removeClass("hidden");
   };
 
+  /**
+   * Hide the log terminal
+   */
   log.hide = function () {
     $("#toggle-logs button.toggle").text("show");
     $panelBody.addClass("hidden");
   };
 
+  /**
+   * Toggle visibility of the log terminal
+   */
   log.toggle = function () {
     if ($panelBody.hasClass("hidden")) {
       log.show();
@@ -46,6 +61,11 @@ export function setUpLog() {
 
   $("#toggle-logs").click(log.toggle);
 
+  /**
+   * Write message to xterm and store it in the download buffer
+   *
+   * @param {string} msg Message to write to the terminal & add to message buffer
+   */
   log.writeAndStore = function (msg) {
     logMessages.push(msg);
     log.write(msg);

binderhub/static/js/src/repo.js

@@ -1,5 +1,8 @@
 import { BASE_URL } from "./constants";
 
+/**
+ * Dict holding cached values of API request to _config endpoint
+ */
 let configDict = {};
 
 function setLabels() {
@@ -18,6 +21,9 @@ function setLabels() {
   $("label[for=repository]").text(text);
 }
 
+/**
+ * Update labels for various inputboxes based on user selection of repo provider
+ */
 export function updateRepoText() {
   if (Object.keys(configDict).length === 0) {
     const configUrl = BASE_URL + "_config";

binderhub/static/js/src/urls.js

@@ -2,6 +2,17 @@ import { makeBadgeMarkup } from "./badge";
 import { getBuildFormValues } from "./form";
 import { BADGE_BASE_URL, BASE_URL } from "./constants";
 
+/**
+ * Generate a shareable binder URL for given repository
+
+ * @param {string} providerPrefix prefix denoting what provider was selected
+ * @param {string} repo repo to build
+ * @param {[string]} ref optional ref in this repo to build
+ * @param {string} path Path to launch after this repo has been built
+ * @param {string} pathType Type of thing to open path with (raw url, notebook file, lab, etc)
+ *
+ * @returns {string|null} A URL that can be shared with others, and clicking which will launch the repo
+ */
 function v2url(providerPrefix, repository, ref, path, pathType) {
   // return a v2 url from a providerPrefix, repository, ref, and (file|url)path
   if (repository.length === 0) {
@@ -30,6 +41,9 @@ function v2url(providerPrefix, repository, ref, path, pathType) {
   return url;
 }
 
+/**
+ * Update the shareable URL and badge snippets in the UI based on values user has entered in the form
+ */
 export function updateUrls(formValues) {
   if (typeof formValues === "undefined") {
     formValues = getBuildFormValues();