Improve javadoc

src/java/io/factorhouse/kpow/StreamsRegistry.java

@@ -174,7 +174,8 @@ public StreamsRegistry(Properties props) {
      *
      * @param streams     the {@link KafkaStreams} instance representing the application to be registered.
      * @param topology    the {@link Topology} of the Kafka Streams application, which defines its processing logic.
-     * @param keyStrategy the {@link KeyStrategy} used to determine the keying of records sent to Kpow's internal Kafka topic.
+     * @param keyStrategy the {@link KeyStrategy} defining the keying mechanism for metrics data written
+     *                    to Kpow's internal Kafka topic.
      * @return a {@link StreamsAgent} representing the registered application, or {@code null} if registration fails.
      * @throws IllegalArgumentException if any of the provided parameters are {@code null}.
      * @see #unregister(StreamsAgent)

src/java/io/factorhouse/kpow/key/ClientIdKeyStrategy.java

@@ -1,11 +1,21 @@
 package io.factorhouse.kpow.key;
 
 /**
- * This key strategy relies on the client ID and application ID from the active KafkaStreams instance, eliminating the need for an AdminClient.
- * <p>
- * However, in a multi-cluster Kpow deployment where the same application ID is used across multiple environments (e.g., staging, dev, prod),
- * Kpow cannot determine which cluster the Kafka Streams instance is associated with.
- * </p>
+ * A {@link KeyStrategy} implementation that derives the key for metrics data using the client ID
+ * and application ID of the active Kafka Streams instance.
+ *
+ * <p>This strategy simplifies the configuration process by relying solely on the client ID
+ * and application ID, eliminating the need for a Kafka {@link org.apache.kafka.clients.admin.AdminClient}.
+ * It is particularly suitable for constrained environments where creating an {@code AdminClient}
+ * may not be feasible or appropriate due to resource limitations or security concerns.</p>
+ *
+ * <p><b>Important:</b> In a multi-cluster Kpow deployment, where the same application ID and client ID
+ * are used across multiple environments (e.g., staging, development, production), this strategy
+ * cannot determine which cluster the Kafka Streams instance is associated with. This limitation may
+ * impact the accuracy of metrics alignment in the Kpow UI for such setups.</p>
+ *
+ * <p>This strategy is most effective in single-cluster deployments, lightweight environments, or
+ * scenarios where client IDs and application IDs are guaranteed to be unique across clusters.</p>
  */
 public class ClientIdKeyStrategy implements KeyStrategy {
 

src/java/io/factorhouse/kpow/key/ClusterIdKeyStrategy.java

@@ -6,8 +6,12 @@
 import org.apache.kafka.clients.admin.DescribeClusterResult;
 
 /**
- * The default key strategy uses the cluster ID, obtained via an {@link org.apache.kafka.clients.admin.Admin#describeCluster()}  call.
- * This AdminClient is created once during registry initialization and then closed.
+ * A {@link KeyStrategy} implementation that uses the Kafka cluster ID as the primary identifier
+ * for keying metrics data in Kpow's internal Kafka topic.
+ * <p>This key strategy uses the cluster ID, obtained via an {@link org.apache.kafka.clients.admin.Admin#describeCluster()} call.</p>
+ * <p>This AdminClient is created once during registry initialization and then closed.</p>
+ * <p>This is the default and recommended keying strategy for Kpow, as it provides a robust way
+ * to uniquely associate metrics data with a specific Kafka cluster.</p>
  */
 public class ClusterIdKeyStrategy implements KeyStrategy {
 

src/java/io/factorhouse/kpow/key/KeyStrategy.java

@@ -2,13 +2,16 @@
 
 /**
  * Defines the key strategy used by Kpow's streams agent.
- *
- * This interface specifies how metrics data should be keyed when writing to Kpow's internal snapshots topic.
+ * <p>This interface specifies how metrics data should be keyed when writing to Kpow's internal snapshots topic.</p>
  */
 public interface KeyStrategy {
     /**
      * Resolves the unique key for metric records based on the provided clientID and applicationID of the registered Kafka Streams application.
      *
+     * <p>The resolved key, represented as a {@link Taxon}, serves as the primary identifier for grouping
+     * and organizing metrics data in Kpow's snapshots topic. This enables Kpow to align the metrics with
+     * the correct Kafka Streams application in the UI.</p>
+     *
      * @param clientId   The client ID of the registered streams application.
      * @param applicationId The application ID of the registered Kafka streams application.
      * @return The unique Taxon object representing the key.

src/java/io/factorhouse/kpow/key/Taxon.java

@@ -1,15 +1,22 @@
 package io.factorhouse.kpow.key;
 
 /**
- * Taxon is an internal class built to resolve the IDs of the KeyStrategy.
+ * An internal class which represents a hierarchical identifier used by Kpow's {@link KeyStrategy} to key metrics data.
  */
-class Taxon {
+public class Taxon {
 
     private final String domain;
     private final String domainId;
     private final String object;
     private final String objectId;
 
+    /**
+     * Constructs a new Taxon instance.
+     * @param domain the domain of the taxon
+     * @param domainId the domain ID of the taxon
+     * @param object the object of the taxon
+     * @param objectId the object ID of the taxon
+     */
     public Taxon(
         String domain,
         String domainId,