[SPARK-52602] Document all public classes

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/BaseResource.java

@@ -27,6 +27,16 @@
 import org.apache.spark.k8s.operator.status.BaseState;
 import org.apache.spark.k8s.operator.status.BaseStatus;
 
+/**
+ * Base class for Spark Kubernetes Operator's custom resources like SparkApplication and
+ * SparkCluster.
+ *
+ * @param <S> The type of the state.
+ * @param <AS> The type of the attempt summary.
+ * @param <STATE> The type of the state.
+ * @param <SPEC> The type of the spec.
+ * @param <STATUS> The type of the status.
+ */
 public class BaseResource<
     S,
     AS extends BaseAttemptSummary,

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/Constants.java

@@ -19,6 +19,7 @@
 
 package org.apache.spark.k8s.operator;
 
+/** Constants used in the Spark Kubernetes Operator. */
 @SuppressWarnings("PMD.DataClass")
 public class Constants {
   public static final String API_GROUP = "spark.apache.org";

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/SparkApplication.java

@@ -32,6 +32,7 @@
 import org.apache.spark.k8s.operator.status.ApplicationStateSummary;
 import org.apache.spark.k8s.operator.status.ApplicationStatus;
 
+/** SparkApplication is the Custom Resource Definition (CRD) for a Spark application. */
 @JsonInclude(JsonInclude.Include.NON_NULL)
 @JsonDeserialize()
 @Group(Constants.API_GROUP)

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/SparkApplicationList.java

@@ -22,5 +22,6 @@
 import io.fabric8.kubernetes.api.model.DefaultKubernetesResourceList;
 import lombok.NoArgsConstructor;
 
+/** List of SparkApplications. */
 @NoArgsConstructor
 public class SparkApplicationList extends DefaultKubernetesResourceList<SparkApplication> {}

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/SparkCluster.java

@@ -32,6 +32,7 @@
 import org.apache.spark.k8s.operator.status.ClusterStateSummary;
 import org.apache.spark.k8s.operator.status.ClusterStatus;
 
+/** SparkCluster is the Custom Resource Definition (CRD) for a Spark cluster. */
 @JsonInclude(JsonInclude.Include.NON_NULL)
 @JsonDeserialize()
 @Group(Constants.API_GROUP)

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/SparkClusterList.java

@@ -22,5 +22,6 @@
 import io.fabric8.kubernetes.api.model.DefaultKubernetesResourceList;
 import lombok.NoArgsConstructor;
 
+/** List of SparkClusters. */
 @NoArgsConstructor
 public class SparkClusterList extends DefaultKubernetesResourceList<SparkCluster> {}

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/spec/ApplicationSpec.java

@@ -31,6 +31,7 @@
 import lombok.EqualsAndHashCode;
 import lombok.NoArgsConstructor;
 
+/** Spec for a Spark application. */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/spec/ApplicationTimeoutConfig.java

@@ -26,6 +26,7 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/** Application timeout configuration. */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/spec/ApplicationTolerations.java

@@ -26,6 +26,7 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/** Toleration settings for a Spark application. */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/spec/BaseApplicationTemplateSpec.java

@@ -27,6 +27,7 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/** Base class for application template specs for driver and executors. */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/spec/BaseSpec.java

@@ -28,6 +28,7 @@
 
 import org.apache.spark.k8s.operator.diff.Diffable;
 
+/** Base spec for all custom resources. */
 @Data
 @JsonInclude(JsonInclude.Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/spec/ClusterSpec.java

@@ -28,6 +28,7 @@
 import lombok.EqualsAndHashCode;
 import lombok.NoArgsConstructor;
 
+/** Spec for a Spark cluster. */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/spec/ClusterTolerations.java

@@ -25,6 +25,7 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/** Toleration settings for a Spark cluster. */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/spec/ConfigMapSpec.java

@@ -28,6 +28,7 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/** Spec for a ConfigMap. */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/spec/DriverServiceIngressSpec.java

@@ -28,6 +28,7 @@
 import lombok.Builder;
 import lombok.Data;
 
+/** Spec for a driver service ingress. */
 @Data
 @Builder
 @JsonInclude(JsonInclude.Include.NON_NULL)

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/spec/MasterSpec.java

@@ -28,6 +28,7 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/** Spec for a Spark master. */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/spec/RestartConfig.java

@@ -26,6 +26,7 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/** Restart configuration for a Spark application. */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/spec/RuntimeVersions.java

@@ -27,6 +27,7 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/** Runtime versions for a Spark application or cluster. */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/spec/WorkerInstanceConfig.java

@@ -25,6 +25,7 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/** Config tolerations of worker instances for the cluster. */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/spec/WorkerSpec.java

@@ -29,6 +29,7 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/** Spec for a Spark worker. */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/status/ApplicationAttemptSummary.java

@@ -27,6 +27,7 @@
 import lombok.Getter;
 import lombok.ToString;
 
+/** Summary of a Spark application attempt. */
 @Getter
 @EqualsAndHashCode(callSuper = true)
 @ToString(callSuper = true)

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/status/ApplicationState.java

@@ -32,6 +32,7 @@
 import lombok.Setter;
 import lombok.ToString;
 
+/** Represents the state of a Spark application. */
 @ToString(callSuper = true)
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(JsonInclude.Include.NON_NULL)

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/status/ApplicationStatus.java

@@ -34,6 +34,7 @@
 import org.apache.spark.k8s.operator.spec.RestartConfig;
 import org.apache.spark.k8s.operator.spec.RestartPolicy;
 
+/** Represents the status of a Spark application. */
 @EqualsAndHashCode(callSuper = true)
 @ToString(callSuper = true)
 @JsonInclude(JsonInclude.Include.NON_NULL)

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/status/AttemptInfo.java

@@ -28,6 +28,7 @@
 import lombok.NoArgsConstructor;
 import lombok.ToString;
 
+/** Information about an attempt. */
 @NoArgsConstructor
 @AllArgsConstructor
 @Builder

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/status/BaseAttemptSummary.java

@@ -26,6 +26,7 @@
 import lombok.RequiredArgsConstructor;
 import lombok.ToString;
 
+/** Base class for attempt summaries. */
 @EqualsAndHashCode
 @ToString
 @Getter

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/status/BaseState.java

@@ -26,6 +26,11 @@
 import lombok.AllArgsConstructor;
 import lombok.Data;
 
+/**
+ * Base class for state information.
+ *
+ * @param <T> The type of the current state summary.
+ */
 @Data
 @AllArgsConstructor
 @JsonInclude(JsonInclude.Include.NON_NULL)

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/status/BaseStatus.java

@@ -29,6 +29,13 @@
 import lombok.Getter;
 import lombok.ToString;
 
+/**
+ * Base class for status information.
+ *
+ * @param <S> The type of the state summary.
+ * @param <STATE> The type of the state.
+ * @param <AS> The type of the attempt summary.
+ */
 @ToString
 @EqualsAndHashCode
 @JsonInclude(JsonInclude.Include.NON_NULL)

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/status/ClusterAttemptSummary.java

@@ -27,6 +27,7 @@
 import lombok.Getter;
 import lombok.ToString;
 
+/** Summary of a Spark cluster attempt. */
 @Getter
 @EqualsAndHashCode(callSuper = true)
 @ToString(callSuper = true)

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/status/ClusterState.java

@@ -29,6 +29,7 @@
 import lombok.EqualsAndHashCode;
 import lombok.ToString;
 
+/** Represents the state of a Spark cluster. */
 @ToString(callSuper = true)
 @EqualsAndHashCode(callSuper = true)
 @JsonInclude(JsonInclude.Include.NON_NULL)

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/status/ClusterStatus.java

@@ -27,6 +27,7 @@
 import lombok.EqualsAndHashCode;
 import lombok.ToString;
 
+/** Represents the status of a Spark cluster. */
 @EqualsAndHashCode(callSuper = true)
 @ToString(callSuper = true)
 @JsonInclude(JsonInclude.Include.NON_NULL)

spark-operator-api/src/main/java/org/apache/spark/k8s/operator/utils/ModelUtils.java

@@ -38,6 +38,7 @@
 import org.apache.spark.k8s.operator.SparkApplication;
 import org.apache.spark.k8s.operator.spec.ApplicationSpec;
 
+/** Utility class for Kubernetes model operations. */
 public final class ModelUtils {
 
   public static final ObjectMapper objectMapper = new ObjectMapper();

spark-operator/src/main/java/org/apache/spark/k8s/operator/SparkOperator.java

@@ -57,7 +57,7 @@
 /**
  * Entry point for Spark Operator. Bootstrap the operator app by starting watch and reconciler for
  * SparkApps, starting watch for hot property loading, if enabled, and starting metrics server with
- * sentinel monitor if enabled
+ * sentinel monitor if enabled.
  */
 @Slf4j
 public class SparkOperator {

spark-operator/src/main/java/org/apache/spark/k8s/operator/client/KubernetesClientFactory.java

@@ -27,7 +27,7 @@
 import okhttp3.Interceptor;
 import okhttp3.OkHttpClient;
 
-/** Build Kubernetes Client with metrics configured */
+/** Factory for building Kubernetes clients with metrics configured. */
 public final class KubernetesClientFactory {
 
   private KubernetesClientFactory() {}

spark-operator/src/main/java/org/apache/spark/k8s/operator/config/ConfigOption.java

@@ -31,7 +31,11 @@
 
 import org.apache.spark.k8s.operator.utils.ModelUtils;
 
-/** Config options for Spark Operator. Supports primitive and serialized JSON */
+/**
+ * Config options for Spark Operator. Supports primitive and serialized JSON.
+ *
+ * @param <T> The type of the config option's value.
+ */
 @RequiredArgsConstructor
 @AllArgsConstructor
 @EqualsAndHashCode

spark-operator/src/main/java/org/apache/spark/k8s/operator/context/BaseContext.java

@@ -23,6 +23,11 @@
 
 import org.apache.spark.k8s.operator.BaseResource;
 
+/**
+ * Base class for context objects.
+ *
+ * @param <CR> The type of the custom resource.
+ */
 public abstract class BaseContext<CR extends BaseResource<?, ?, ?, ?, ?>> {
   public abstract CR getResource();
 

spark-operator/src/main/java/org/apache/spark/k8s/operator/listeners/BaseStatusListener.java

@@ -21,7 +21,12 @@
 import org.apache.spark.k8s.operator.BaseResource;
 import org.apache.spark.k8s.operator.status.BaseStatus;
 
-/** Custom listeners, if added, would be listening to resource status change */
+/**
+ * Custom listeners, if added, would be listening to resource status change.
+ *
+ * @param <STATUS> The type of the status.
+ * @param <CR> The type of the custom resource.
+ */
 public abstract class BaseStatusListener<
     STATUS extends BaseStatus<?, ?, ?>, CR extends BaseResource<?, ?, ?, ?, STATUS>> {
   public abstract void listenStatus(CR resource, STATUS prevStatus, STATUS updatedStatus);

spark-operator/src/main/java/org/apache/spark/k8s/operator/metrics/JVMMetricSet.java

@@ -31,6 +31,7 @@
 import com.codahale.metrics.jvm.MemoryUsageGaugeSet;
 import com.codahale.metrics.jvm.ThreadStatesGaugeSet;
 
+/** A MetricSet for JVM metrics. */
 public class JVMMetricSet implements MetricSet {
 
   /** Refer codahale FileDescriptorRatioGauge for the definition */

spark-operator/src/main/java/org/apache/spark/k8s/operator/metrics/MetricsService.java

@@ -28,7 +28,7 @@
 import com.sun.net.httpserver.HttpServer;
 import lombok.extern.slf4j.Slf4j;
 
-/** Start Http service at endpoint /prometheus, exposing operator metrics */
+/** Start Http service at endpoint /prometheus, exposing operator metrics. */
 @Slf4j
 public class MetricsService {
   HttpServer server;

spark-operator/src/main/java/org/apache/spark/k8s/operator/metrics/MetricsSystem.java

@@ -36,6 +36,7 @@
 import org.apache.spark.metrics.sink.Sink;
 import org.apache.spark.metrics.source.Source;
 
+/** Manages the metrics system for the Spark Operator. */
 @Slf4j
 public class MetricsSystem {
   private final AtomicBoolean running = new AtomicBoolean(false);

spark-operator/src/main/java/org/apache/spark/k8s/operator/metrics/MetricsSystemFactory.java

@@ -28,7 +28,7 @@
 
 import org.apache.spark.k8s.operator.config.SparkOperatorConfManager;
 
-/** Factory for MetricsSystem */
+/** Factory for MetricsSystem. */
 public final class MetricsSystemFactory {
   public static final String METRIC_PREFIX = "spark.metrics.conf.operator.";
   public static final String SINK = "sink.";

spark-operator/src/main/java/org/apache/spark/k8s/operator/metrics/PrometheusPullModelHandler.java

@@ -37,7 +37,7 @@
 
 import org.apache.spark.metrics.sink.PrometheusServlet;
 
-/** Serves as simple Prometheus sink (pull model), presenting metrics snapshot as HttpHandler */
+/** Serves as simple Prometheus sink (pull model), presenting metrics snapshot as HttpHandler. */
 @Slf4j
 public class PrometheusPullModelHandler extends PrometheusServlet implements HttpHandler {
   private static final String EMPTY_RECORD_VALUE = "[]";

spark-operator/src/main/java/org/apache/spark/k8s/operator/metrics/healthcheck/SentinelManager.java

@@ -43,7 +43,7 @@
 import org.apache.spark.k8s.operator.utils.Utils;
 
 /**
- * Sentinel manager monitors dedicated sentinel resources to make sure the operator is healthy
+ * Sentinel manager monitors dedicated sentinel resources to make sure the operator is healthy.
  *
  * @param <CR> custom resource type
  */

spark-operator/src/main/java/org/apache/spark/k8s/operator/metrics/source/KubernetesMetricsInterceptor.java

@@ -40,6 +40,7 @@
 
 import org.apache.spark.metrics.source.Source;
 
+/** Interceptor for Kubernetes client to collect metrics. */
 @Slf4j
 public class KubernetesMetricsInterceptor implements Interceptor, Source {
   final MetricRegistry metricRegistry;

spark-operator/src/main/java/org/apache/spark/k8s/operator/metrics/source/OperatorJosdkMetrics.java

@@ -48,6 +48,7 @@
 import org.apache.spark.util.Clock;
 import org.apache.spark.util.SystemClock;
 
+/** Metrics for the Java Operator SDK. */
 @Slf4j
 public class OperatorJosdkMetrics implements Source, Metrics {
   public static final String FINISHED = "finished";

spark-operator/src/main/java/org/apache/spark/k8s/operator/metrics/source/OperatorJvmSource.java

@@ -24,6 +24,7 @@
 import org.apache.spark.k8s.operator.metrics.JVMMetricSet;
 import org.apache.spark.metrics.source.Source;
 
+/** Source for JVM metrics. */
 public class OperatorJvmSource implements Source {
   @Override
   public String sourceName() {