add a bit of documentation

data/db.js

@@ -1,12 +1,27 @@
 "use strict";
 
+/** A wrapper around an IndexedDB.
+ *
+ * This wrapper handles the following tasks:
+ * 1. Open the connection to the database.
+ * 2. Transform the events of that request into a form more suitable for UI.
+ * 3. Manage the DB schema (object stores, indexes, migrations, …).
+ *
+ * In production this also behaves as a singleton, while allowing multiple
+ * instances specifically for testing.
+ */
 export default class WbDb extends EventTarget {
+  /** The name of the event fired when the state changes. */
   static get EVENT_CHANGE() { return "change"; }
 
+  /** The name of the `IDBDatabase`. */
   static get DB_NAME() { return "watterblock"; }
+  /** The name of the test `IDBDatabase`. */
   static get DB_NAME_TEST() { return "test-watterblock"; }
+  /** The currently correct DB version. */
   static get DB_VERSION() { return 1; }
 
+  /** The name of the `IDBObjectStore` for `Session`s. */
   static get OS_SESSIONS() { return "sessions"; }
 
   /** Whether the WbDb constructor may be called. */

data/db.test.js

@@ -1,5 +1,12 @@
 "use strict";
 
+// Please note that the singleton behavior of the `WbDb` class in production
+// can currently not be tested. The actual singleton cannot be used because
+// that would mean opening the database, and potentially performing a
+// transaction that is not yet finished, potentially leading to data loss.
+// Setting up a second singleton instance for testing is possible, but would
+// not actually test the production variant.
+
 import { Round } from "../models/round.js";
 import WbDb from "./db.js";
 

models/game.js

@@ -9,8 +9,10 @@ import RoundResult from "./round_result.js";
  * a points goal.
  *
  * This class keeps track of individual rounds and their results, and sets up
- * new ones until the game is finished. It also has a `results` property, that
+ * new ones until the game is finished. It also has a `result` property, that
  * calculates who won and how many points they earned.
+ *
+ * Note that game points are punitive, players want to avoid earning them.
  */
 export default class Game extends EventTarget {
   /** The event triggered when the game is finished. */
@@ -134,6 +136,7 @@ export default class Game extends EventTarget {
     }
   }
 
+  /** #handleRoundFinished, but bound to this instance. */
   #boundRoundFinishedHandler = this.#handleRoundFinished.bind(this);
 
   /** Export the data of this `Game` as a plain JS object with fields.

models/round.js

@@ -31,6 +31,8 @@ export const Team = Object.freeze({
  * This project is not concerned with creating an online version of the game,
  * the aim is to create a convenient score keeping system. Therefore this class
  * only implements the raising mechanics, and no actual game play.
+ *
+ * Note that round points are positive, players want to accumulate them.
  */
 export class Round extends EventTarget {
   /** The event triggered when the round is won. */

models/round_result.js

@@ -2,6 +2,7 @@
 
 import { Round, Team } from "./round.js";
 
+/** A finished round of Watten. */
 export default class RoundResult {
   /** How many points the round was worth.
    * @type {number}

models/session.js

@@ -3,6 +3,19 @@
 import Game from "./game.js";
 import { Team } from "./round.js";
 
+/** A session of Watten.
+ *
+ * A session consists of several games, and can be continued for as long as the
+ * players want to.
+ *
+ * This class keeps track of various games and offers the functionality to
+ * start new ones. It also has a `result` property, that calculates the current
+ * points totals.
+ *
+ * Note that game points are punitive, players want to avoid earning them.
+ * Sessions are also self contained, there is no higher construct they are a
+ * part of.
+ */
 export default class Session {
   /** The ID of this session. */
   id = null;
@@ -93,6 +106,7 @@ export default class Session {
     this.#currentGame = null;
   }
 
+  /** #gameFinishedHandler, but bound to this instance. */
   #boundGameFinishedHandler = this.#gameFinishedHandler.bind(this);
 
   constructor(value) {