From 0fdc0038a5fb18a1ceb18a0dd9e0dd4489383f03 Mon Sep 17 00:00:00 2001
From: slhafzjw <slhafzjw@slhaf.work>
Date: Mon, 4 May 2026 17:47:20 +0800
Subject: [PATCH] docs(partnerctl-support): add KDoc for source build spec and
 external module manifest models

---
 .../partner/ctl/support/external_module.kt    | 28 +++++++++++++++++++
 .../slhaf/partner/ctl/support/source_build.kt | 21 ++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/PartnerCtl/src/main/java/work/slhaf/partner/ctl/support/external_module.kt b/PartnerCtl/src/main/java/work/slhaf/partner/ctl/support/external_module.kt
index f50e75fd..4c18d05b 100644
--- a/PartnerCtl/src/main/java/work/slhaf/partner/ctl/support/external_module.kt
+++ b/PartnerCtl/src/main/java/work/slhaf/partner/ctl/support/external_module.kt
@@ -15,12 +15,27 @@ fun loadExternalModule(): Set<ModuleManifest> {
     return loadModules().filter { !it.withGateway }.toSet()
 }
 
+/**
+ * External module manifest loaded from the module registry.
+ *
+ * This type models the JSON contract of a registry entry. Paths are stored as strings here because
+ * manifests are external JSON documents. Runtime code should convert path-like fields to [java.nio.file.Path]
+ * only when building execution specs.
+ */
 @Serializable
 data class ModuleManifest(
+    /** Stable module id. Also used as gateway channel name for gateway modules. */
     val id: String,
+
+    /** Human-readable module name. */
     val name: String,
+
+    /** Whether this module can provide a gateway channel. */
     val withGateway: Boolean,
+
+    /** Human-readable module description shown before installation. */
     val description: String = "",
+
     val source: Source,
     val install: Install,
     val config: Config? = null,
@@ -28,21 +43,34 @@ data class ModuleManifest(
 
 @Serializable
 data class Source(
+    /** Git repository URL used as the module source. */
     val url: String,
+
+    /** Directory name for the cloned repository under the temporary build directory. */
     val sourceDirName: String,
+
+    /** Build command executed with the cloned source root as working directory. */
     val buildCommand: List<String>,
+
+    /** Directory containing build artifacts, relative to the cloned source root. */
     val artifactDirectory: String,
+
+    /** Glob pattern used inside [artifactDirectory] to select the artifact to install. */
     val artifactPattern: String,
 )
 
 @Serializable
 data class Install(
+    /** Install target path, relative to Partner home. */
     val target: String,
 )
 
 @Serializable
 data class Config(
+    /** Config file target path, relative to Partner home. */
     val target: String,
+
+    /** Interactive fields used to generate the module config object. */
     val fields: List<Field> = emptyList(),
 )
 
diff --git a/PartnerCtl/src/main/java/work/slhaf/partner/ctl/support/source_build.kt b/PartnerCtl/src/main/java/work/slhaf/partner/ctl/support/source_build.kt
index 3dd161bf..172ae09c 100644
--- a/PartnerCtl/src/main/java/work/slhaf/partner/ctl/support/source_build.kt
+++ b/PartnerCtl/src/main/java/work/slhaf/partner/ctl/support/source_build.kt
@@ -5,13 +5,34 @@ import java.nio.file.Files
 import java.nio.file.Path
 import java.nio.file.StandardCopyOption
 
+/**
+ * Runtime specification for building a JVM/Maven project from source and installing one built artifact.
+ *
+ * Path semantics:
+ * - [sourceDirName] is the child directory name created under a temporary build directory.
+ * - [artifactDirectory] is resolved relative to the cloned source root: tempDir/sourceDirName/artifactDirectory.
+ * - [installRelativePath] is resolved relative to Partner home: home/installRelativePath.
+ */
 data class SourceBuildInstallSpec(
+    /** Display name used in prompt messages. */
     val displayName: String,
+
+    /** Git repository URL used by `git clone --depth 1`. */
     val repoUrl: String,
+
+    /** Directory name for the cloned repository under the temporary build directory. */
     val sourceDirName: String,
+
+    /** Build command executed with the cloned source root as working directory. */
     val buildCommand: List<String>,
+
+    /** Directory containing build artifacts, relative to the cloned source root. */
     val artifactDirectory: Path,
+
+    /** Selects the artifact to install from the resolved artifact directory. */
     val artifactSelector: (Path) -> Path?,
+
+    /** Install target path, relative to Partner home. */
     val installRelativePath: Path,
 )