Improves some documentation.

I was starting to get confused.

add-on/build.gradle

@@ -1,3 +1,12 @@
+/*
+ * Copyright (c) 2021 William Hubbard. All Rights Reserved.
+ *
+ * This module contains the browser addon that handles most of the logic for internet songs. When the :browser module is
+ * built, this addon is added to the browser's list of extensions. Then, when it is run, the addon will start the
+ * intermediary program. Then, it will receive commands from the interface through the intermediary application and
+ * manipulate the browser state based on those commands. It will then send the results of those commands back through
+ * the intermediary. The addon will also periodically shoot off updates to the browser.
+ */
 import org.apache.tools.ant.taskdefs.condition.Os
 
 import java.nio.file.Files
@@ -6,10 +15,17 @@ import java.nio.file.StandardCopyOption
 import java.util.stream.Stream
 
 configurations {
+    /**
+     * This configuration is used to export the packaged addon for installation into a browser.
+     */
     addonBuild {
         canBeConsumed = true
         canBeResolved = false
     }
+    /**
+     * The nativeApp configuration is used to import a native application that this addon will start when the browser
+     * does.
+     */
     nativeApp.extendsFrom runtime
 }
 
@@ -30,7 +46,7 @@ extension.description = "A link between the Universal Music Player and the web b
 extension.id = "universalmusic@regis.edu"
 
 /**
- * Creates an addon manifest for running
+ * Creates an addon manifest that defines details for the native application that is run when the app starts.
  */
 abstract class BuildManifest extends DefaultTask {
     @OutputFile
@@ -66,7 +82,7 @@ abstract class BuildManifest extends DefaultTask {
 }
 
 /**
- *
+ * Installs the addon manifest, adding registery keys on Windows and creating the appropriate files on Mac and Linux.
  */
 abstract class InstallAddon extends DefaultTask {
     @InputFile
@@ -97,16 +113,25 @@ dependencies {
     nativeApp project(path: ":addonInter", configuration: 'nativeBuild')
 }
 
+/**
+ * Creates a build manifest that defines details for the native application defined by nativeApp dependencies that will
+ * be run.
+ */
 tasks.register('buildManifest', BuildManifest) {
     manifests = new File(buildDir, "${extension.name.get()}.json")
 }
 
+/**
+ * Registers the build manifest to the OS, allowing for the native application to run properly.
+ * This task depends on buildManifest
+ */
 def installAddon = tasks.register('installAddon', InstallAddon) {
     inputFile = buildManifest.manifests
 }
 
 /**
  * Creates a packaged (albiet unsigned) Firefox addon from the src/main directory.
+ * This task is finished by calling installAddon
  */
 tasks.register('zipAddon', Zip) {
     dependsOn configurations.nativeApp
@@ -146,6 +171,9 @@ tasks.register("clean", Delete) {
     followSymlinks = false
 }
 
+/*
+ * Exports the packaged addon task.
+ */
 artifacts {
     addonBuild(zipAddon)
 }

add-on/src/addon/javascript/background.js

@@ -1,3 +1,52 @@
+/*
+ * Copyright (c) 2021 William Hubbard. All Rights Reserved.
+ *
+ * The background script forms the core of the addon. Running when the browser starts, it starts the native application
+ * (the intermediary program that connects to the interface). The native application will send it commands in the
+ * format of a JSON object containing a "messageNum" field (containing a session-unique identifier for that message) and
+ * "message" (containing the actual message, of which can be of any type). The message data will be forwarded to several
+ * listeners. The listeners will output a single value (or throw an error). In response to either, the addon will send
+ * a JSON object back to the native application in the following format:
+ *
+ * <code>
+ *  {
+ *      "messageNum": 0, // The ID of the message that this response corresponds to
+ *      "message": { //A wrapper that contains, among other things, the return data
+ *          "type": "edu.regis.universeplayer.browserCommands.CommandReturn", // An identifier that tells the interface to treat this data as a return value for a command
+ *          "returnValue": null, // The actual data returned by the listeners. In the event of an error, this will be null.
+ *          "confirmation": { // Contains extra metadata about how the command was executed
+ *              "type": "edu.regis.universeplayer.browserCommands.CommandConfirmation", // Another identifier for the interface
+ *              "message": "Done", // A human-readable message on the results of execution. For non-error returns, this will simply be "done."
+                "errorCode": { // If an error was thrown, this object will contain data on that. Otherwise, it will be null
+                    "type": "edu.regis.universeplayer.browserCommands.BrowserError",
+                    "name": "",
+                    "message": "",
+                    "stack", []
+ *          }
+ *      }
+ *  }
+ * </code>
+ *
+ * The default one (registered by this script) does the majority of processing. This default listener takes an object
+ * with a single "type" field that corresponds to an instance of edu.regis.universeplayer.browserCommands.BrowserQuery
+ * in the Java interface. Using that "type" field, it determines what action to take and uses extra data within the
+ * message object. Should the message be something delegated to a foreground tab (i.e. controlling a YouTube video),
+ * the listener will forward the message to the tab in the following format before returning:
+ *
+ * <code>
+ *  {
+ *      "num": 0, // The ID of the tab-specific message. This is independent of the "messageNum" field above
+ *      "message": {} // A copy of the actual message sent.
+ *  }
+ * </code>
+ *
+ * Either way,
+ *
+ * Then, whenever it receives a command from the application,
+ * it will forward that command to several listeners. One of those listeners, a default one registered by this script,
+ * does the majority of processing. If the message is marked for a specific tab (one running the foreground.js script),
+ * the message is forwarded to that tab for further processing before retrieving the value. Either way,
+ */
 let logger = new Logger("background");
 
 logger.pushUpdate = function (message)
@@ -357,6 +406,12 @@ function queryTab(tab, message)
     });
 }
 
+/**
+ * Contains a list of listeners that will act upon messages from the native app.
+ *
+ * @see handleMessage(message)
+ */
+var listeners = [
 /**
  * A callback for when the native application sends a message.
  *
@@ -365,7 +420,7 @@ function queryTab(tab, message)
  *                              or a new value.
  * @return Either the value passed on returnValue or a new value.
  */
-var listeners = [function (message, returnValue) {
+function (message, returnValue) {
     if (typeof message == "object" && "type" in message)
     {
         let type = message.type;

add-on/src/addon/javascript/foreground.js

@@ -1,3 +1,9 @@
+/*
+ * Copyright (c) 2021 William Hubbard. All Rights Reserved.
+ *
+ * The foreground script serves as the core for managing playback of a song. It receives messages forwarded from the background
+ */
+
 let logger = new Logger("foreground");
 console.debug("Loading foreground.js");
 let background;
@@ -70,7 +76,16 @@ function handleMessage(message)
 
 /**
  * Calling this function will forward playback data to the browser background (and by extension, the
- * interface) as specified by the parameters.
+ * interface) as specified by the parameters. The sent data will be in the following format:
+ *
+ * <code>
+ *  {
+ *      "type": "edu.regis.universeplayer.PlaybackInfo",
+ *      "currentSong": {},
+ *      "status": "STATUS",
+ *      "playTime": 0
+ *  }
+ * </code>
  *
  * @param {string} status   The playback status. This can be "PLAYING", "PAUSED", "STOPPED",
  *                          "FINISHED", or "EMPTY"
@@ -88,7 +103,14 @@ function onStatusUpdate(status, time, songData)
 }
 
 /**
- * Forwards an update to the background (and by extension, the interface).
+ * Forwards an update to the background (and by extension, the interface). The data will be in the following format:
+ *
+ * <code>
+ *  {
+ *      "type": "update",
+ *      "data": {} // The actual data sent.
+ *  }
+ * </code>
  *
  * @param {object|Promise} response The data to forward. If this data is a Promise, then the data
  *                                  will be forwarded upon completion.
@@ -110,10 +132,16 @@ function sendUpdate(response)
 }
 
 $(function () {
+    /*
+     * Preinitializes a few things
+     */
     while (preload.length > 0)
     {
         preload.pop()();
     }
+    /*
+     * Connects to the background.
+     */
     background = browser.runtime.connect({name:"universalMusic"});
 
 //    sendUpdate("loaded");