docs: Add missing documentation

Author: briancorbinxyz

.idea/kotlinc.xml

@@ -73,7 +73,8 @@ if (enablePreviewFeatures) {
 
     tasks.withType<Javadoc>() {
         (options as StandardJavadocDocletOptions).apply {
-            addBooleanOption("-enable-preview", true)    
+            addStringOption("Xmaxwarns", "1")
+            addBooleanOption("-enable-preview", true)
             source = "24"
         }
     }

api/build.gradle.kts

@@ -7,17 +7,16 @@
 import org.xxdc.oss.example.transport.TransportConfiguration;
 import org.xxdc.oss.example.transport.TransportServer;
 
-/**
- * The `PlayerNode` interface represents a player in a game. It provides methods to get the player's
- * marker and apply the player's next move to the game state.
- *
- * <p>The `Local` implementation of `PlayerNode` represents a local player, where the player's logic
- * is implemented directly in the application.
- *
- * <p>The `Remote` implementation of `PlayerNode` represents a remote player, where the player's
- * logic is implemented in a separate process and communicated with the application through a
- * transport mechanism.
- */
+/// The `PlayerNode` interface represents a player in a game. It provides methods to get the
+// player's
+/// marker and apply the player's next move to the game state.
+///
+/// The `Local` implementation of `PlayerNode` represents a local player, where the player's logic
+/// is implemented directly in the application.
+///
+/// The `Remote` implementation of `PlayerNode` represents a remote player, where the player's
+/// logic is implemented in a separate process and communicated with the application through a
+/// transport mechanism.
 public sealed interface PlayerNode extends ToIntFunction<GameState> {
 
   /**

api/src/main/java/org/xxdc/oss/example/PlayerNode.java

@@ -3,7 +3,7 @@
 import java.net.InetAddress;
 import java.net.UnknownHostException;
 
-/** Provides a utility to generate a player identifier string for a given `PlayerNode`. */
+/// Provides a utility to generate a player identifier string for a given `PlayerNode`.
 public class PlayerPrinter {
 
   /**

api/src/main/java/org/xxdc/oss/example/PlayerPrinter.java

@@ -4,8 +4,11 @@
 import java.util.stream.Gatherer.Integrator;
 import org.xxdc.oss.example.GameState;
 
+/** A collection of analyzers for gathering data points from the game state. */
 public class Analyzers {
 
+  private Analyzers() {}
+
   static class GathererState {
     private GameState prevGameState;
     private int currMoveNumber;

api/src/main/java/org/xxdc/oss/example/analysis/Analyzers.java

@@ -6,7 +6,8 @@
 /// A strategic turning point in a game of Tic-Tac-Toe.
 public sealed interface StrategicTurningPoint {
 
-  static enum PriorityLevel {
+  /// Priority/severity level of the strategic turning point.
+  enum PriorityLevel {
     HIGH,
     MEDIUM,
     LOW

api/src/main/java/org/xxdc/oss/example/analysis/StrategicTurningPoint.java

@@ -6,8 +6,11 @@
 import java.lang.constant.MethodTypeDesc;
 import java.lang.invoke.MethodHandles;
 
+/// Naive FIFO bot implementation that implements the CustomBotStrategy interface.
+/// This bot uses a FIFO (First-In-First-Out) strategy to make moves on the game board.
 public class NaiveFifoGenerator {
 
+  /// Generates a new instance of the NaiveFifoGenerator class.
   public static CustomBotStrategy newGeneratedBot() {
     try {
       byte[] classBytes = generateBotClass();
@@ -19,6 +22,7 @@ public static CustomBotStrategy newGeneratedBot() {
     }
   }
 
+  /// Generates the bytecode for the NaiveFifoGenerator class.
   private static byte[] generateBotClass() {
     return ClassFile.of()
         .build(

api/src/main/java/org/xxdc/oss/example/bot/custom/NaiveFifoGenerator.java

@@ -2,6 +2,9 @@
 
 import org.xxdc.oss.example.analysis.StrategicTurningPoint;
 
+/**
+ * Persona / personality that provides a comment on a strategic turning point in the game.
+ */
 public interface CommentaryPersona {
   String comment(StrategicTurningPoint turningPoint);
 }

api/src/main/java/org/xxdc/oss/example/commentary/CommentaryPersona.java

@@ -2,6 +2,9 @@
 
 import org.xxdc.oss.example.analysis.StrategicTurningPoint;
 
+/**
+ * Persona / personality that provides an acknowledgement of a strategic turning point in the game.
+ */
 public class DefaultAckCommentaryPersona implements CommentaryPersona {
 
   @Override

api/src/main/java/org/xxdc/oss/example/commentary/DefaultAckCommentaryPersona.java

@@ -2,6 +2,9 @@
 
 import org.xxdc.oss.example.analysis.StrategicTurningPoint;
 
+/**
+ * Persona / personality that provides a comment on a strategic turning point in the game.
+ */
 public class DefaultLiveCommentaryPersona implements CommentaryPersona {
 
   @Override

api/src/main/java/org/xxdc/oss/example/commentary/DefaultLiveCommentaryPersona.java

@@ -2,6 +2,9 @@
 
 import org.xxdc.oss.example.analysis.StrategicTurningPoint;
 
+/**
+ * Persona that provides post-game analysis commentary on a strategic turning point in the game.
+ */
 public class DefaultPostAnalysisCommentaryPersona implements CommentaryPersona {
 
   @Override

api/src/main/java/org/xxdc/oss/example/commentary/DefaultPostAnalysisCommentaryPersona.java

@@ -4,6 +4,9 @@
 
 import org.xxdc.oss.example.analysis.StrategicTurningPoint;
 
+/**
+ * Persona that provides energetic, esports-style commentary on a strategic turning point in the game.
+ */
 public class EsportsLiveCommentaryPersona implements CommentaryPersona {
 
   @Override

api/src/main/java/org/xxdc/oss/example/commentary/EsportsLiveCommentaryPersona.java

@@ -2,7 +2,10 @@
 
 import org.xxdc.oss.example.analysis.StrategicTurningPoint;
 
-public class EsportsPostAnalysisConmmentaryPersona implements CommentaryPersona {
+/**
+ * Persona that provides esports-style post-game analysis commentary on a strategic turning point in the game.
+ */
+public class EsportsPostAnalysisCommentaryPersona implements CommentaryPersona {
 
   @Override
   public String comment(StrategicTurningPoint turningPoint) {

api/src/main/java/org/xxdc/oss/example/commentary/EsportsPostAnalysisConmmentaryPersona.java renamed to api/src/main/java/org/xxdc/oss/example/commentary/EsportsPostAnalysisCommentaryPersona.java

@@ -10,7 +10,7 @@
 import java.lang.System.Logger.Level;
 import org.xxdc.oss.example.bot.BotStrategy;
 import org.xxdc.oss.example.commentary.EsportsLiveCommentaryPersona;
-import org.xxdc.oss.example.commentary.EsportsPostAnalysisConmmentaryPersona;
+import org.xxdc.oss.example.commentary.EsportsPostAnalysisCommentaryPersona;
 
 /** A simple java tic-tac-toe game. */
 public class App {
@@ -40,7 +40,7 @@ private void logLiveCommentary(Game game) {
 
   private void logPostAnalysisCommentary(Game game) {
     log.log(Level.INFO, "Post-Game Analysis:");
-    var commentary = new EsportsPostAnalysisConmmentaryPersona();
+    var commentary = new EsportsPostAnalysisCommentaryPersona();
     game.history().stream()
         .gather(strategicTurningPoints())
         .map(commentary::comment)

app/src/main/java/org/xxdc/oss/example/App.java

@@ -9,7 +9,7 @@
 import java.lang.System.Logger.Level;
 import org.xxdc.oss.example.bot.BotStrategy;
 import org.xxdc.oss.example.commentary.EsportsLiveCommentaryPersona;
-import org.xxdc.oss.example.commentary.EsportsPostAnalysisConmmentaryPersona;
+import org.xxdc.oss.example.commentary.EsportsPostAnalysisCommentaryPersona;
 
 /// A simple java tic-tac-toe game with a bot playing another bot for training
 /// the JDK for AOT class loading and linking. NB: Uses bots so not all paths are
@@ -56,7 +56,7 @@ private void logLiveCommentary(Game game) {
 
   private void logPostAnalysisCommentary(Game game) {
     log.log(Level.INFO, "Post-Game Analysis:");
-    var commentary = new EsportsPostAnalysisConmmentaryPersona();
+    var commentary = new EsportsPostAnalysisCommentaryPersona();
     game.history().stream()
         .gather(strategicTurningPoints())
         .map(commentary::comment)

app/src/main/java/org/xxdc/oss/example/AppTrainer.java

@@ -51,4 +51,3 @@ tasks.register("checkSigningEnvSetup") {
     }
 }
 
-