Improved documentation

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/k8s/InitContainerBootstrap.scala

@@ -25,8 +25,9 @@ import org.apache.spark.deploy.k8s.Config._
 import org.apache.spark.deploy.k8s.Constants._
 
 /**
- * This is separated out from the init-container steps API because this component can be reused to
- * set up the init-container for executors as well.
+ * Bootstraps an init-container for downloading remote dependencies. This is separated out from
+ * the init-container steps API because this component can be used to bootstrap init-containers
+ * for both the driver and executors.
  */
 private[spark] class InitContainerBootstrap(
     initContainerImage: String,

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/k8s/submit/DriverConfigOrchestrator.scala

@@ -34,7 +34,9 @@ import org.apache.spark.util.Utils
  * Figures out and returns the complete ordered list of needed DriverConfigurationSteps to
  * configure the Spark driver pod. The returned steps will be applied one by one in the given
  * order to produce a final KubernetesDriverSpec that is used in KubernetesClientApplication
- * to construct and create the driver pod.
+ * to construct and create the driver pod. It uses the InitContainerConfigOrchestrator to
+ * configure the driver init-container if one is needed, i.e., when there are remote dependencies
+ * to localize.
  */
 private[spark] class DriverConfigOrchestrator(
     kubernetesAppId: String,

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/k8s/submit/steps/BaseDriverConfigurationStep.scala

@@ -28,7 +28,7 @@ import org.apache.spark.deploy.k8s.submit.KubernetesDriverSpec
 import org.apache.spark.internal.config.{DRIVER_CLASS_PATH, DRIVER_MEMORY, DRIVER_MEMORY_OVERHEAD}
 
 /**
- * Represents the initial setup required for the driver.
+ * Performs basic configuration for the driver pod.
  */
 private[spark] class BaseDriverConfigurationStep(
     kubernetesAppId: String,

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/k8s/submit/steps/DriverConfigurationStep.scala

@@ -19,7 +19,7 @@ package org.apache.spark.deploy.k8s.submit.steps
 import org.apache.spark.deploy.k8s.submit.KubernetesDriverSpec
 
 /**
- * Represents a step in preparing the Kubernetes driver.
+ * Represents a step in configuring the Spark driver pod.
  */
 private[spark] trait DriverConfigurationStep {
 

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/k8s/submit/steps/DriverInitContainerBootstrapStep.scala

@@ -26,8 +26,10 @@ import org.apache.spark.deploy.k8s.submit.{InitContainerUtil, KubernetesDriverSp
 import org.apache.spark.deploy.k8s.submit.steps.initcontainer.{InitContainerConfigurationStep, InitContainerSpec}
 
 /**
- * Configures the init-container that bootstraps dependencies into the driver pod, including
- * building a ConfigMap that will be mounted into the init-container. The ConfigMap carries
+ * Configures the driver init-container that localizes remote dependencies into the driver pod.
+ * It applies the given InitContainerConfigurationSteps in the given order to produce a final
+ * InitContainerSpec that is then used to configure the driver pod with the init-container attached.
+ * It also builds a ConfigMap that will be mounted into the init-container. The ConfigMap carries
  * configuration properties for the init-container.
  */
 private[spark] class DriverInitContainerBootstrapStep(

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/k8s/submit/steps/initcontainer/BaseInitContainerConfigurationStep.scala

@@ -20,6 +20,10 @@ import org.apache.spark.deploy.k8s.{InitContainerBootstrap, PodWithDetachedInitC
 import org.apache.spark.deploy.k8s.Config._
 import org.apache.spark.deploy.k8s.submit.KubernetesFileUtils
 
+/**
+ * Performs basic configuration for the driver init-container with most of the work delegated to
+ * the given InitContainerBootstrap.
+ */
 private[spark] class BaseInitContainerConfigurationStep(
     sparkJars: Seq[String],
     sparkFiles: Seq[String],
@@ -47,6 +51,7 @@ private[spark] class BaseInitContainerConfigurationStep(
       FILES_DOWNLOAD_LOCATION.key -> filesDownloadPath) ++
       remoteJarsConf ++
       remoteFilesConf
+
     val bootstrapped = bootstrap.bootstrapInitContainer(
       PodWithDetachedInitContainer(
         spec.driverPod,

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/k8s/submit/steps/initcontainer/InitContainerConfigOrchestrator.scala

@@ -23,9 +23,10 @@ import org.apache.spark.deploy.k8s.Constants._
 
 /**
  * Figures out and returns the complete ordered list of InitContainerConfigurationSteps required to
- * configure an init-container. The returned steps will be applied in the given order to produce a
- * final InitContainerSpec that is used to construct an init-container. This is only used when an
- * init-container is needed, i.e., when there are remote application dependencies to localize.
+ * configure the driver init-container. The returned steps will be applied in the given order to
+ * produce a final InitContainerSpec that is used to construct the driver init-container in
+ * DriverInitContainerBootstrapStep. This class is only used when an init-container is needed, i.e.,
+ * when there are remote application dependencies to localize.
  */
 private[spark] class InitContainerConfigOrchestrator(
     sparkJars: Seq[String],

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/deploy/k8s/submit/steps/initcontainer/InitContainerConfigurationStep.scala

@@ -17,7 +17,7 @@
 package org.apache.spark.deploy.k8s.submit.steps.initcontainer
 
 /**
- * Represents a step in configuring the init-container for the driver and executors.
+ * Represents a step in configuring the driver init-container.
  */
 private[spark] trait InitContainerConfigurationStep {
 

resource-managers/kubernetes/core/src/main/scala/org/apache/spark/scheduler/cluster/k8s/ExecutorPodFactory.scala

@@ -29,7 +29,18 @@ import org.apache.spark.internal.config.{EXECUTOR_CLASS_PATH, EXECUTOR_JAVA_OPTI
 import org.apache.spark.util.Utils
 
 /**
- * A factory class for configuring and creating executor pods.
+ * A factory class for bootstrapping and creating executor pods with the given bootstrapping
+ * components.
+ *
+ * @param sparkConf Spark configuration
+ * @param mountSecretsBootstrap an optional component for mounting user-specified secrets onto
+ *                              user-specified paths into the executor container
+ * @param initContainerBootstrap an optional component for bootstrapping the executor init-container
+ *                               if one is needed, i.e., when there are remote dependencies to
+ *                               localize
+ * @param initContainerMountSecretsBootstrap an optional component for mounting user-specified
+ *                                           secrets onto user-specified paths into the executor
+ *                                           init-container
  */
 private[spark] class ExecutorPodFactory(
     sparkConf: SparkConf,