@@ -1,6 +1,6 @@
 name: Web play Docker smoke test
 
-# Builds the Docker image and plays the first move of a game through the web server inside it: this checks what can
+# Builds the Docker image and plays the first move of a game through the web server inside it. This checks what can
 # only be checked on Linux in the image (Xvfb, fonts, AWT), as well as the page, the access token and the WebSocket
 # protocol (see web.WebServer).
 on:
 
@@ -42,7 +42,7 @@ COPY --from=build /app/target/tag-classes.jar /tag/tag-classes.jar
 # For the WebServer entry point
 EXPOSE 8080
 
-# Every entry point runs under Xvfb, which the others simply do not use, e.g.
+# Every entry point runs under Xvfb, though only WebServer uses it, e.g.
 #   docker run tag RunGames config=...
 #   docker run -p 8080:8080 tag WebServer games=LawnAndOrder token=...
 ENTRYPOINT ["tini", "--", "xvfb-run", "-a", "-s", "-screen 0 2560x1600x24", \
 
@@ -175,8 +175,8 @@ public Set<Integer> getHumanPlayerIds() {
         return humanPlayerIds;
     }
 
-    /* Read-only access to the standard parts of the GUI, for showing them elsewhere: the web package streams a GUI to
-       a browser, hides these panels, and draws their contents natively in the page. Call on the Swing thread. */
+    /* Read-only access to the standard parts of the GUI, so that they can be shown elsewhere (as the web package
+       does). Call on the Swing thread. */
 
     /**
      * The panel of action buttons made by createActionPanel, or null if this GUI does not use one.
@@ -194,19 +194,19 @@ public JComponent getInfoPanel() {
     }
 
     /**
-     * The action buttons (empty if this GUI has none). A button offers an action when it is visible and has text;
-     * clicking it (doClick) chooses that action, as a click on the GUI would.
+     * The action buttons (empty if this GUI has none). A button offers an action when it is visible and has text, and
+     * doClick chooses it.
      */
     public JButton[] getActionButtons() {
         return actionButtons == null ? new JButton[0] : actionButtons.clone();
     }
 
     /**
-     * The lines of game state information shown in the info panel: status, scores, phase, turn and current player
-     * (not the list of each player's result, which is mostly noise until the game ends).
+     * The lines of game state information shown in the info panel: status, scores, phase, turn and current player.
      */
     public List<String> getGameStateInfo() {
         List<String> lines = new ArrayList<>();
+        // not playerStatus: each player's result is mostly noise until the game ends
         for (JLabel label : new JLabel[]{gameStatus, playerScores, gamePhase, turn, currentPlayer})
             if (label.getText() != null && !label.getText().isEmpty())
                 lines.add(label.getText());
 
@@ -4,10 +4,8 @@
 import java.awt.*;
 
 /**
- * Messages a GUI shows to the player (round over, your turn, ...). On the desktop these are modal dialogs, as
- * JOptionPane shows them. A GUI that is not on a desktop can have them shown another way by setting a handler: the web
- * package does, as a modal dialog would block the one Swing thread shared by every game it serves, and would never
- * reach the browser.
+ * Messages a GUI shows to the player (round over, your turn, ...). On the desktop these are modal dialogs; a GUI shown
+ * elsewhere, as by the web package, has a handler show them. GUIs use this rather than JOptionPane.
  */
 public final class GUIMessages {
 
@@ -44,8 +42,7 @@ public static void show(Component parent, String message) {
     }
 
     /**
-     * As JOptionPane.showConfirmDialog(parent, message, title, optionType, messageType), but with no answer, as the
-     * message is for information only.
+     * As JOptionPane.showConfirmDialog(parent, message, title, optionType, messageType), but with no answer.
      */
     public static void showConfirm(Component parent, String message, String title, int optionType, int messageType) {
         Handler h = handler;
 
@@ -15,11 +15,10 @@
 
 /**
  * Sends the browser what an AI player weighed up for each decision it makes: its most visited actions, with the share
- * of its search each took and their value to it, from {@link AbstractPlayer#getDecisionStats()} (MCTS reports these;
- * players that do not search report nothing, and nothing is sent).
+ * of its search each took and their value to it, from {@link AbstractPlayer#getDecisionStats()}.
  * <p>
- * This shows what the AI knows, including its own hidden information (in a game of simultaneous choices, the card it
- * is about to play), so a session sends it only when the browser player asked for it.
+ * This shows what the AI knows, including its own hidden information (in a game of simultaneous choices, the move it
+ * is about to make).
  */
 class AIInsight implements IGameListener {
 
@@ -41,6 +40,7 @@ public void onEvent(Event event) {
             return;
         AbstractPlayer player = game.getPlayers().get(event.playerID);
         Map<AbstractAction, Map<String, Object>> stats = player.getDecisionStats();
+        // players that do not search (random, say) report nothing
         if (stats == null || stats.isEmpty()) return;
 
         AbstractGameState state = event.state != null ? event.state : game.getGameState();
 
@@ -10,9 +10,9 @@
 import java.util.stream.Collectors;
 
 /**
- * An optional shared secret for the whole server, so that only people sent the link can play. The link is
- * {@code http://host:port/?token=SECRET}: the token is then kept in a cookie (and taken out of the address), and every
- * page, API call and WebSocket must carry it. With no token configured, the server is open.
+ * An optional shared secret for the whole server, so that only people sent the link
+ * ({@code http://host:port/?token=SECRET}) can play. Every page, API call and WebSocket must carry the token, in the
+ * query or in the cookie it sets. With no token configured, the server is open.
  */
 class AccessToken {
 
@@ -39,12 +39,12 @@ boolean isOpen() {
     }
 
     /**
-     * Lets an HTTP request through if it carries the token (in the query, which also sets the cookie, or in the
-     * cookie); otherwise answers 401 and stops it.
+     * Lets an HTTP request through if it carries the token; otherwise answers 401 and stops it.
      */
     void check(Context ctx) {
         if (isOpen()) return;
         String fromQuery = ctx.queryParam("token");
+        // a token in the query sets the cookie, which then carries it
         if (fromQuery != null && matches(fromQuery)) {
             ctx.header("Set-Cookie", COOKIE + "=" + fromQuery + "; Path=/; Max-Age=" + COOKIE_DAYS * 24 * 3600
                     + "; HttpOnly; SameSite=Lax" + (ctx.scheme().equals("https") ? "; Secure" : ""));
@@ -67,14 +67,15 @@ <p>This game server is private. Open it with the link you were sent (it ends in
     }
 
     /**
-     * Whether a WebSocket connection carries the token (in its cookie or query).
+     * Whether a WebSocket connection carries the token.
      */
     boolean allows(WsContext ctx) {
         return isOpen() || matches(ctx.cookie(COOKIE)) || matches(ctx.queryParam("token"));
     }
 
     private boolean matches(String candidate) {
         if (candidate == null) return false;
+        // in constant time, so the time taken gives nothing of the token away
         return MessageDigest.isEqual(token, candidate.getBytes(StandardCharsets.UTF_8));
     }
 
 
@@ -12,12 +12,7 @@
 /**
  * Moves a GUI's standard parts (its action buttons, game state information and history; see
  * {@link AbstractGUIManager#getActionPanel()}) from the streamed image into the page, where the browser draws them
- * natively.
- * <p>
- * The Swing panels are hidden, but stay in being: after every GUI update their contents are read and sent to the
- * browser when they change. An action chosen in the page clicks the same Swing button, and hovering over it sends the
- * button the same mouse events, so whatever a game does on a click or a hover (highlights on the board, say) still
- * happens. A GUI that does not use a standard panel keeps that part in the image.
+ * natively. A GUI that does not use a standard panel keeps that part in the image.
  * <p>
  * Everything here runs on the Swing thread.
  */
@@ -36,6 +31,7 @@ class ChromeReader {
         this.out = out;
         hasActions = gui.getActionPanel() != null && gui.getActionButtons().length > 0;
         hasInfo = gui.getInfoPanel() != null;
+        // hidden, not removed: update still reads them, and choose clicks their buttons
         if (hasActions) gui.getActionPanel().setVisible(false);
         if (hasInfo) gui.getInfoPanel().setVisible(false);
     }
@@ -110,11 +106,13 @@ private void sendHistory(List<String> history) {
     void choose(int i, String label) {
         JButton[] buttons = gui.getActionButtons();
         if (i < 0 || i >= buttons.length || !offers(buttons[i]) || !buttons[i].getText().equals(label)) return;
+        // a click on the Swing button, rather than the action itself, so whatever the game does on a click happens
         buttons[i].doClick(0);
     }
 
     /**
-     * The mouse entering (or leaving) the page's button for action i, passed on to the Swing button.
+     * Passes the mouse entering or leaving the page's button for action i on to the Swing button, so a game's hover
+     * effects (highlights on the board, say) still happen.
      */
     void hover(int i, boolean enter) {
         JButton[] buttons = gui.getActionButtons();
 
@@ -21,9 +21,8 @@
 import java.util.concurrent.TimeUnit;
 
 /**
- * Sends what a frame shows to the browser. Every tick the frame's root pane is painted into an image at a scale set by
- * the session (the browser's device pixel ratio, times the scale it shows the frame at); the image is split into
- * square tiles, and only the tiles that changed since the last tick are sent, each as a PNG.
+ * Sends what a frame shows to the browser. Every tick the frame's root pane is painted into an image, which is split
+ * into square tiles, and the tiles that changed since the last tick are sent, each as a PNG.
  * <p>
  * Each frame is one binary message: a 4-byte big-endian length, a JSON header of that length
  * ({@code {seq, w, h, fw, fh, tiles: [{x, y, w, h, len}]}}), then the tiles' PNG bytes in header order. The image and
 
@@ -15,18 +15,14 @@
 
 /**
  * The games the server offers, and their parameters as a form can show them.
- * <p>
- * A game's parameters are listed only if its parameter class is a {@link TunableParameters}, and then only those of a
- * simple type (numbers, booleans, strings and enums), each with its default and, where the game gives them, its
- * possible values.
  */
 class GameCatalog {
 
     private final List<GameType> games;
 
     /**
-     * @param spec a comma-separated list of game names, or "all" (or empty) for every game with a GUI, by name (less
-     *             the template for new games)
+     * @param spec a comma-separated list of game names, or "all" (or empty) for every game with a GUI except
+     *             GameTemplate, sorted by name
      */
     GameCatalog(String spec) {
         if (spec == null || spec.isBlank() || spec.equalsIgnoreCase("all")) {
@@ -69,12 +65,17 @@ JsonArray describe() {
         return result;
     }
 
+    /**
+     * The game's parameters that a form can set, each with its default and any possible values the game lists.
+     */
     static JsonArray describeParameters(GameType game) {
         JsonArray result = new JsonArray();
+        // only a TunableParameters class lists its parameters
         if (!(game.createParameters(0) instanceof TunableParameters<?> params)) return result;
         for (String name : params.getParameterNames()) {
             Class<?> type = typeOf(params, name);
             String kind = kind(type);
+            // only numbers, booleans, strings and enums
             if (kind == null) continue;
             JsonObject p = new JsonObject();
             p.addProperty("name", name);
 
@@ -16,8 +16,8 @@
 import players.human.HumanGUIPlayer;
 
 import javax.swing.*;
-import java.util.ArrayList;
 import java.awt.*;
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -59,7 +59,7 @@ public class GameSession {
     // the size of the browser's space for the GUI, and its device pixel ratio (Swing thread only)
     private Dimension space;
     private double dpr;
-    // the image is drawn at dpr * the scale the browser shows the frame at (see fitFrame)
+    // image pixels per frame pixel (see fitFrame)
     private volatile double imageScale;
     private volatile long lastActivity = System.currentTimeMillis();
     private final long startedAt = System.currentTimeMillis();
@@ -79,9 +79,7 @@ public GameSession(SessionConfig config, OpponentCatalog opponents, Sender out,
     }
 
     /**
-     * Swing settings for a JVM whose GUIs are all streamed. Swing's own tooltips are switched off, as Swing moves them
-     * on to a real screen and so out of the frame; the InputForwarder sends their text to the browser instead. Messages
-     * a GUI would show in a dialog are sent to its browser.
+     * Swing settings for a JVM whose GUIs are all streamed.
      *
      * @param lookAndFeel "flat" for FlatLaf's light look and feel, or "default" for Swing's own
      */
@@ -90,8 +88,11 @@ public static void configureSwing(String lookAndFeel) {
             FlatLightLaf.setup();
         else if (!lookAndFeel.equalsIgnoreCase("default"))
             throw new IllegalArgumentException("Unknown look and feel (flat or default): " + lookAndFeel);
+        // Swing moves a tooltip on to a real screen, and so out of the frame; the InputForwarder sends their text to
+        // the browser instead
         ToolTipManager.sharedInstance().setEnabled(false);
         JPopupMenu.setDefaultLightWeightPopupEnabled(true);
+        // a message a GUI would show in a dialog goes to the browser of the session the GUI belongs to
         GUIMessages.setHandler((parent, title, message) -> {
             GameSession session = byFrame.get(SwingUtilities.getWindowAncestor(parent));
             if (session != null) session.sendMessage(title, message);
@@ -179,6 +180,7 @@ private void start(int w, int h, double dpr) {
                 sendStarted(seed, players);
                 guiUpdater = new Timer((int) game.getCoreParameters().frameSleepMS, e -> {
                     game.updateGUI(gui, frame);
+                    // a GUI can grow as the game goes on
                     fitFrame();
                     chrome.update();
                     reportProgress();
@@ -238,8 +240,7 @@ private JsonArray playerNames(List<AbstractPlayer> players) {
     }
 
     /**
-     * Tells the browser whose turn it is when that changes, and the results once the game is over. Runs on the Swing
-     * thread, after each GUI update.
+     * Tells the browser whose turn it is when that changes, and the results once the game is over.
      */
     private void reportProgress() {
         AbstractGameState state = game.getGameState();
@@ -274,9 +275,8 @@ private void reportProgress() {
     }
 
     /**
-     * A record of the game so far, for a bug report or to set the game up again: the setup (game, seed, players, every
-     * parameter's value) and the actions taken, described as the browser player saw them (so hiding what they could not
-     * see), and the results if the game is over.
+     * A record of the game so far, for a bug report or to set the game up again. The actions are described as the
+     * browser player saw them.
      */
     private JsonObject gameLog() {
         JsonObject log = new JsonObject();
@@ -327,10 +327,8 @@ private JsonObject gameLog() {
         return log;
     }
 
-    /**
-     * The game's action history. The game thread adds to it, so copying it may meet a change; it is then copied again.
-     */
     private static List<utilities.Pair<Integer, core.actions.AbstractAction>> history(AbstractGameState state) {
+        // the game thread adds to the history, so copying it may meet a change; it is then copied again
         for (int attempt = 0; ; attempt++) {
             try {
                 return state.getHistory();
@@ -356,14 +354,14 @@ private void resize(int w, int h, double dpr) {
     }
 
     /**
-     * Sizes the frame to the browser's space or, where the GUI's layout needs more (many GUIs are laid out at a fixed
-     * size), to a larger frame of the same proportions, which the browser scales down to fit. The layout's own preferred size is used, not the
-     * size the GUI may have set on its panel, as that counts the panels the ChromeReader hides. A GUI can grow as the
-     * game goes on, so this runs after every update. Swing thread only.
+     * Sizes the frame to the browser's space or, where the GUI needs more, to a larger frame of the same proportions,
+     * which the browser scales down to fit. Swing thread only.
      */
     private void fitFrame() {
         Container content = frame.getContentPane();
         LayoutManager layout = content.getLayout();
+        // Many GUIs are laid out at a fixed size. The layout's own preferred size is used, not the size the GUI may have
+        // set on its panel, as that counts the panels the ChromeReader hides.
         Dimension needed = layout != null ? layout.preferredLayoutSize(content) : content.getPreferredSize();
         // scaled down by s, a frame of the space's proportions fills the space exactly
         double s = Math.min(1, Math.min((double) space.width / needed.width, (double) space.height / needed.height));
@@ -378,23 +376,22 @@ private void fitFrame() {
     }
 
     /**
-     * Ends the session because the browser player has been away too long: tells the browser, then closes the
-     * connection, which stops the session.
+     * Tells the browser the game was ended for want of activity, and closes the connection (which stops the session).
      */
     public void endIdle(int minutes) {
         sendError("This game was ended after " + minutes + (minutes == 1 ? " minute" : " minutes") + " without activity.");
         out.close();
     }
 
     /**
-     * Ends the game (the game thread is interrupted while it waits for the browser player's action) and disposes of
-     * the frame.
+     * Ends the game and disposes of the frame.
      */
     public synchronized void stop() {
         if (stopped) return;
         stopped = true;
         if (!started) return;
         game.setStopped(true);
+        // the game thread may be waiting for the browser player's action
         gameThread.interrupt();
         streamer.stop();
         SwingUtilities.invokeLater(() -> {