Docs

modules/core/src/main/kotlin/com/metalbear/mirrord/MirrordApi.kt

@@ -156,10 +156,35 @@ private const val MIRRORD_LS_RICH_OUTPUT_ENV = "MIRRORD_LS_RICH_OUTPUT"
  * Interact with mirrord CLI using this API.
  */
 class MirrordApi(private val service: MirrordProjectService, private val projectEnvVars: Map<String, String>?) {
-    data class FoundTarget(val path: String, val available: Boolean)
+    /**
+     * New format of found target returned from `mirrord ls`.
+     */
+    data class FoundTarget(
+        /**
+         * Path to the target, e.g `pod/my-pod`.
+         */
+        val path: String,
+        /**
+         * Whether this target can be selected.
+         */
+        val available: Boolean
+    )
+
+    /**
+     * New format of `mirrord ls`, enabled by setting MIRRORD_LS_RICH_OUTPUT_ENV to `true`.
+     */
     private data class RichOutput(
+        /**
+         * Targets found in the namespace.
+         */
         val targets: Array<FoundTarget>,
+        /**
+         * Namespace where the lookup was done.
+         */
         @SerializedName("current_namespace") val currentNamespace: String,
+        /**
+         * All namespaces available to the user.
+         */
         val namespaces: Array<String>
     ) {
         override fun equals(other: Any?): Boolean {
@@ -183,7 +208,23 @@ class MirrordApi(private val service: MirrordProjectService, private val project
         }
     }
 
-    class MirrordLsOutput(val targets: List<FoundTarget>, val currentNamespace: String?, val namespaces: List<String>?)
+    /**
+     * Output of `mirrord ls`.
+     */
+    class MirrordLsOutput(
+        /**
+         * List of found targets.
+         */
+        val targets: List<FoundTarget>,
+        /**
+         * Namespace where the lookup was done.
+         */
+        val currentNamespace: String?,
+        /**
+         * All namespaces avaiable to the user.
+         */
+        val namespaces: List<String>?
+    )
 
     private class MirrordLsTask(cli: String, projectEnvVars: Map<String, String>?) : MirrordCliTask<MirrordLsOutput>(cli, "ls", null, projectEnvVars) {
         override fun compute(project: Project, process: Process, setText: (String) -> Unit): MirrordLsOutput {

modules/core/src/main/kotlin/com/metalbear/mirrord/MirrordExecDialog.kt

@@ -20,28 +20,73 @@ import javax.swing.*
 import javax.swing.event.DocumentEvent
 import javax.swing.event.DocumentListener
 
+/**
+ * Target and namespace selection dialog.
+ * @param project for getting the MirrordNotifier.
+ * @param getTargets function used to fetch targets from the cluster.
+ *                   Accepts the name of a namespace where the lookup should be done.
+ *                   If no name is given, the default value from the mirrord config should be user.
+ */
 class MirrordExecDialog(private val project: Project, private val getTargets: (String?) -> MirrordApi.MirrordLsOutput) : DialogWrapper(project, true) {
-    data class UserSelection(val target: String?, val namespace: String?)
+    /**
+     * Target and namespace selected by the user.
+     */
+    data class UserSelection(
+        /**
+         * Path to the target, e.g `pod/my-pod`.
+         * null if targetless.
+         */
+        val target: String?,
+        /**
+         * Optional target namespace override.
+         */
+        val namespace: String?
+    )
 
     companion object {
+        /**
+         * Dummy label we use in the dialog to allow the user for explicitly selecting the targetless mode.
+         * There can be no clash with real target labels, because each of those starts with a target type, e.g `pod/`.
+         */
         private const val TARGETLESS_SELECTION_LABEL = "No Target (\"targeteless\")"
+
+        /**
+         * Placeholder value for the target filter.
+         */
         private const val TARGET_FILTER_PLACEHOLDER = "Filter targets..."
     }
 
+    /**
+     * Targets fetched from the cluster.
+     */
     private var fetched: MirrordApi.MirrordLsOutput = getTargets(null)
 
+    /**
+     * Whether we are currently refreshing the widgets with new content.
+     *
+     * This is set in `refresh` and inspected in the custom `namespaceOptions` data model.
+     * Prevents infinite loops and other bugs.
+     */
     private var refreshing: Boolean = false
 
+    /**
+     * List of targets available in the current namespace.
+     */
     private val targetOptions: JBList<String> = JBList(emptyList<String>()).apply {
         selectionMode = ListSelectionModel.SINGLE_SELECTION
         minimumSize = Dimension(250, 350)
     }
 
+    /**
+     * Dropdown allowing for switching namespaces.
+     */
     private val namespaceOptions: ComboBox<String> = ComboBox(object : DefaultComboBoxModel<String>() {
         override fun setSelectedItem(anObject: Any?) {
             super.setSelectedItem(anObject)
 
             if (refreshing) {
+                // If we don't check this, we're going to have problems.
+                // `refresh` changes data in this data model, which triggers this function.
                 return
             }
 
@@ -54,7 +99,7 @@ class MirrordExecDialog(private val project: Project, private val getTargets: (S
     })
 
     /**
-     * Whether to show pods.
+     * Checkbox allowing for filtering out pods from the target list.
      */
     private val showPods: JBCheckBox = JBCheckBox("Pods", MirrordSettingsState.instance.mirrordState.showPodsInSelection ?: true).apply {
         this.addActionListener {
@@ -63,7 +108,7 @@ class MirrordExecDialog(private val project: Project, private val getTargets: (S
     }
 
     /**
-     * Whether to show deployments.
+     * Checkbox allowing for filtering out deployments from the target list.
      */
     private val showDeployments: JBCheckBox = JBCheckBox("Deployments", MirrordSettingsState.instance.mirrordState.showDeploymentsInSelection ?: true).apply {
         this.addActionListener {
@@ -72,14 +117,17 @@ class MirrordExecDialog(private val project: Project, private val getTargets: (S
     }
 
     /**
-     * Whether to show rollouts.
+     * Checkbox allowing for filtering out rollouts from the target list.
      */
     private val showRollouts: JBCheckBox = JBCheckBox("Rollouts", MirrordSettingsState.instance.mirrordState.showRolloutsInSelection ?: true).apply {
         this.addActionListener {
             refresh()
         }
     }
 
+    /**
+     * Text field allowing for searching targets by path.
+     */
     private val targetFilter = JTextField().apply {
         val field = this
 
@@ -140,19 +188,31 @@ class MirrordExecDialog(private val project: Project, private val getTargets: (S
         maximumSize = Dimension(10000, 30)
     }
 
+    /**
+     * Label for `targetFilter` and `targetOptions`.
+     */
     private val selectTargetLabel = JLabel("Select Target").apply {
         alignmentX = JLabel.LEFT_ALIGNMENT
         font = JBFont.create(font.deriveFont(Font.BOLD), false)
     }
 
+    /**
+     * Label for `namespaceOptions`.
+     */
     private val selectNamespaceLabel = JLabel("Select Namespace").apply {
         alignmentX = JLabel.LEFT_ALIGNMENT
         font = JBFont.create(font.deriveFont(Font.BOLD), false)
     }
 
+    /**
+     * Small vertical gap between widgets.
+     */
     private val verticalSeparator: Component
         get() = Box.createRigidArea(Dimension(0, 10))
 
+    /**
+     * Small horizontal gap between widgets.
+     */
     private val horizontalSeparator: Component
         get() = Box.createRigidArea(Dimension(10, 0))
 
@@ -162,6 +222,9 @@ class MirrordExecDialog(private val project: Project, private val getTargets: (S
         init()
     }
 
+    /**
+     * Updates widgets' content based on what we fetched from the cluster (`fetched` field).
+     */
     private fun refresh() {
         refreshing = true
         try {
@@ -238,6 +301,11 @@ class MirrordExecDialog(private val project: Project, private val getTargets: (S
         )
     }
 
+    /**
+     * Displays the dialog and returns the user selection.
+     *
+     * Returns null if the user cancelled.
+     */
     fun showAndGetSelection(): UserSelection? {
         if (!showAndGet()) {
             return null

modules/core/src/main/kotlin/com/metalbear/mirrord/MirrordExecManager.kt

@@ -21,7 +21,7 @@ class MirrordExecManager(private val service: MirrordProjectService) {
     /**
      * Attempts to show the target selection dialog and allow user to select the mirrord target.
      *
-     * @return target chosen by the user (or special constant for targetless mode)
+     * @return target chosen by the user
      * @throws ProcessCanceledException if the dialog cannot be displayed
      */
     private fun chooseTarget(
@@ -103,6 +103,11 @@ class MirrordExecManager(private val service: MirrordProjectService) {
         })
     }
 
+    /**
+     * Resolves path to the mirrord config and the session target.
+     *
+     * Returns null if mirrord is disabled.
+     */
     private fun prepareStart(
         wslDistribution: WSLDistribution?,
         product: String,