Continuing to add documentation

Chris Pollett [2023-01-06 01:Jan:th]
Continuing to add documentation
Filename
game.js
diff --git a/game.js b/game.js
index f1eb61d..31c5361 100644
--- a/game.js
+++ b/game.js
@@ -5,16 +5,19 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  */
- /**
-  * Frise Game Library
-  */
+/**
+ * Frise Game Engine
+ *
+ * A light-weight engine for writing interactive fiction and games.
+ *
+ */
 /**
  * Common Global Functions
  */
 /**
  * Returns an Element object from the current document which has the provided
  * id.
- * @param {String} id of element trying to get an object for
+ * @param {string} id of element trying to get an object for
  * @return {Element} desired element if exists, else null
  */
 function elt(id)
@@ -24,7 +27,7 @@ function elt(id)
 /**
  * Returns a collection of objects for Element's that match the provided Element
  * name in the current document.
- * @param {String} name of HTML/XML Element that want from current document
+ * @param {string} name of HTML/XML Element that want from current document
  * @return {HTMLCollection} of matching Element's
  */
 function tag(name)
@@ -33,7 +36,7 @@ function tag(name)
 }
 /**
  * Returns a list of Node's which match the CSS selector string provided.
- * @param {String} a CSS selector string to match against current document
+ * @param {string} a CSS selector string to match against current document
  * @return {NodeList} of matching Element's
  */
 function sel(selector)
@@ -41,14 +44,22 @@ function sel(selector)
     return document.querySelectorAll(selector);
 }
 /**
+ * Returns a game object based on the element in the current document of the
+ * provided id.
  *
+ * @param {string} id of element in current document.
+ * @return {Object} a game object.
  */
 function xelt(id)
 {
     return makeGameObject(elt(id));
 }
 /**
+ * Returns an array of game objects based on the elements in the current
+ * document that match the CSS selector passed to it.
  *
+ * @param {string} a CSS selector for objects in the current document
+ * @return {Array} of game objects based on the tags that matched the selector
  */
 function xsel(selector)
 {
@@ -96,8 +107,8 @@ function makeGameObjects(tag_objects)
 }
 /**
  * Upper cases first letter of a string
- * @param {String} str string to upper case first letter of
- * @return {String} result of upper-casing
+ * @param {string} str string to upper case first letter of
+ * @return {string} result of upper-casing
  */
 function upperFirst(str)
 {
@@ -108,10 +119,14 @@ function upperFirst(str)
     return upper_first + str.slice(1);
 }
 /**
- * Used as part of the closure of makeGameObject so as that every game
+ * Used as part of the closure of makeGameObject so that every game
  * object has an integer id.
+ * @type {number}
  */
 var object_counter = 0;
+/**
+ * @param {Element}
+ */
 function makeGameObject(dom_object)
 {
     if (!dom_object || dom_object.tagName.substring(0, 2) != "X-") {
@@ -401,7 +416,7 @@ class Location
                     if (icon) {
                         section =
                             section.replace(html_fragment, html_fragment_mod +
-                            "<figure><img src='"+speaker.icon+"' " +
+                            "<figure><img src='" + speaker.icon + "' " +
                             "loading='lazy' ></figure><div>" + name +
                             "</div><hr>");
                     }
@@ -412,15 +427,38 @@ class Location
     }
 }
 /**
- *
+ * Classed used to encapsulate an interactive story game. It has fields
+ * to track the locations and objects in the game, the history of moves of
+ * the game, and how many moves have been made. It has methods to
+ * take a turn in such a game, to save state, load state,
+ * restore prev/next state from history, render the state of such
+ * a game.
  */
 class Game
 {
+    /**
+     *
+     */
     timestamp;
+    /**
+     *
+     */
     objects;
+    /**
+     *
+     */
     locations;
+    /**
+     *
+     */
     history;
+    /**
+     *
+     */
     future_history;
+    /**
+     *
+     */
     constructor()
     {
         this.history = [];
@@ -856,15 +894,18 @@ class Game
     }
 }
 /**
- *
+ * Global game object used to track one interactive story fiction game
+ * @type {Game}
  */
 var game;
 /**
- *
+ * Flag used to tell if current user is interacting on a mobile device or not
+ * @type {boolean}
  */
 var is_mobile = window.matchMedia("(max-width: 1000px)").matches;
 /**
- *
+ * Module initialization function, used to set up the game object corrsponding
+ * to the current HTML document.
  */
 async function initGame()
 {
ViewGit