Add developer API docs and Dokka Javadoc support

Author: 54895y

build.gradle.kts

@@ -1,11 +1,13 @@
 import io.izzel.taboolib.gradle.*
 import org.gradle.api.publish.maven.MavenPublication
+import org.jetbrains.dokka.gradle.DokkaTask
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 plugins {
     java
     `maven-publish`
     id("io.izzel.taboolib") version "2.0.36"
+    id("org.jetbrains.dokka") version "1.9.20"
     kotlin("jvm") version "2.3.0"
 }
 
@@ -48,6 +50,18 @@ tasks.withType<JavaCompile> {
     options.encoding = "UTF-8"
 }
 
+tasks.withType<DokkaTask>().configureEach {
+    moduleName.set("MatrixLib API")
+    dokkaSourceSets.configureEach {
+        includes.from("docs/api/overview.md")
+        jdkVersion.set(8)
+        skipDeprecated.set(false)
+        reportUndocumented.set(false)
+        noStdlibLink.set(false)
+        noJdkLink.set(false)
+    }
+}
+
 kotlin {
     compilerOptions {
         jvmTarget = JvmTarget.fromTarget("1.8")
@@ -60,6 +74,16 @@ configure<JavaPluginExtension> {
     withSourcesJar()
 }
 
+val dokkaJavadocJar by tasks.registering(Jar::class) {
+    dependsOn(tasks.named("dokkaJavadoc"))
+    archiveClassifier.set("javadoc")
+    from(tasks.named("dokkaJavadoc"))
+}
+
+tasks.named("assemble") {
+    dependsOn(dokkaJavadocJar)
+}
+
 val sharedApiRepoDirCandidates = listOf(
     layout.projectDirectory.dir("../_publish/matrix-api"),
     layout.projectDirectory.dir("../../_publish/matrix-api")
@@ -74,6 +98,7 @@ publishing {
         create<MavenPublication>("matrixlibApi") {
             from(components["java"])
             artifactId = "matrixlib-api"
+            artifact(dokkaJavadocJar)
         }
     }
     repositories {
@@ -89,3 +114,9 @@ tasks.register("publishMatrixApi") {
     description = "Publish MatrixLib API artifact to the shared local repository."
     dependsOn("publishAllPublicationsToMatrixPublicRepository")
 }
+
+tasks.register("generateJavadoc") {
+    group = "documentation"
+    description = "Generate Javadoc-style API docs with Dokka."
+    dependsOn("dokkaJavadoc")
+}

docs/api/overview.md

@@ -0,0 +1,56 @@
+Module MatrixLib API
+
+MatrixLib API 面向 Matrix 系列插件开发者，当前提供：
+
+- 统一品牌与控制台输出
+- 文本与 YAML bundle
+- 菜单与动作执行
+- Bukkit / Folia 兼容探测
+- 共享货币与结算
+- 全息兼容桥接
+- bStats 注册封装
+- GitHub Releases 更新检查与审批下载
+
+## Code Tree
+
+```text
+src/main/kotlin/com/y54895/matrixlib/
+├─ MatrixLib.kt
+├─ api/
+│  ├─ action/ActionApi.kt
+│  ├─ brand/MatrixBranding.kt
+│  ├─ compat/CompatApi.kt
+│  ├─ console/MatrixConsoleVisuals.kt
+│  ├─ economy/MatrixEconomy.kt
+│  ├─ hologram/
+│  │  ├─ MatrixHologramRequest.kt
+│  │  ├─ MatrixHolograms.kt
+│  │  └─ internal/
+│  ├─ menu/MenuApi.kt
+│  ├─ metrics/MatrixBStats.kt
+│  ├─ resource/MatrixResourceFiles.kt
+│  ├─ text/
+│  │  ├─ MatrixText.kt
+│  │  └─ MatrixYamlBundle.kt
+│  └─ update/MatrixPluginUpdates.kt
+├─ command/MatrixLibCommands.kt
+└─ metrics/BStatsMetrics.kt
+```
+
+Public API recommendation:
+
+- Prefer types under `api/`
+- Treat `api/hologram/internal/` as provider internals
+- Treat `command/` and `metrics/` as MatrixLib runtime wiring, not downstream extension points
+
+推荐入口类型：
+
+- `MatrixBranding`
+- `MatrixText`
+- `MatrixYamlBundle`
+- `MenuLoader`
+- `MenuRenderer`
+- `MatrixEconomy`
+- `MatrixHolograms`
+- `MatrixBStats`
+- `MatrixPluginUpdates`

src/main/kotlin/com/y54895/matrixlib/api/action/ActionApi.kt

@@ -4,14 +4,34 @@ import com.y54895.matrixlib.api.text.MatrixText
 import org.bukkit.Sound
 import org.bukkit.entity.Player
 
+/**
+ * Runtime action context used by Matrix menu and UI layers.
+ *
+ * @property player player who triggered the action set
+ * @property placeholders resolved placeholders for action interpolation
+ * @property backAction optional callback used by the built-in `back` action
+ */
 data class ActionContext(
     val player: Player,
     val placeholders: Map<String, String>,
     val backAction: Runnable? = null
 )
 
+/**
+ * Executes Matrix action strings against a player context.
+ *
+ * Supported built-in actions:
+ * - `close`
+ * - `back`
+ * - `tell:<message>`
+ * - `sound:<SOUND>-<volume>-<pitch>`
+ * - any other non-blank string is treated as a player command
+ */
 object ActionExecutor {
 
+    /**
+     * Execute a list of actions in order.
+     */
     fun execute(context: ActionContext, actions: List<String>) {
         actions.forEach { executeSingle(context, it) }
     }

src/main/kotlin/com/y54895/matrixlib/api/brand/MatrixBranding.kt

@@ -1,5 +1,8 @@
 package com.y54895.matrixlib.api.brand
 
+/**
+ * Shared branding descriptor used by Matrix console, text, and command surfaces.
+ */
 data class MatrixBranding(
     val displayName: String,
     val rootCommand: String,

src/main/kotlin/com/y54895/matrixlib/api/console/MatrixConsoleVisuals.kt

@@ -5,16 +5,27 @@ import com.y54895.matrixlib.api.text.MatrixText
 import org.bukkit.Bukkit
 import taboolib.common.platform.function.info
 
+/**
+ * Key-value line rendered inside Matrix console lifecycle blocks.
+ */
 data class MatrixConsoleFact(
     val label: String,
     val value: String
 )
 
+/**
+ * Shared lifecycle banner renderer for Matrix plugins.
+ *
+ * This API keeps console output visually consistent across the Matrix series.
+ */
 object MatrixConsoleVisuals {
 
     private const val MIN_BORDER_WIDTH = 66
     private val colorCodePattern = Regex("&[0-9a-fk-orA-FK-OR]")
 
+    /**
+     * Render the boot block used during plugin load.
+     */
     fun renderBoot(
         branding: MatrixBranding,
         headline: String,
@@ -30,6 +41,9 @@ object MatrixConsoleVisuals {
         )
     }
 
+    /**
+     * Render an arbitrary lifecycle stage block.
+     */
     fun renderStage(
         branding: MatrixBranding,
         stage: String,
@@ -44,6 +58,9 @@ object MatrixConsoleVisuals {
         )
     }
 
+    /**
+     * Render the ready block used after plugin enable completed successfully.
+     */
     fun renderReady(
         branding: MatrixBranding,
         version: String,
@@ -58,6 +75,9 @@ object MatrixConsoleVisuals {
         )
     }
 
+    /**
+     * Render the failure block used when startup aborts.
+     */
     fun renderFailure(
         branding: MatrixBranding,
         reason: String
@@ -70,6 +90,9 @@ object MatrixConsoleVisuals {
         )
     }
 
+    /**
+     * Render the shutdown block used during plugin disable.
+     */
     fun renderShutdown(
         branding: MatrixBranding,
         details: List<MatrixConsoleFact> = emptyList()

src/main/kotlin/com/y54895/matrixlib/api/hologram/MatrixHologramRequest.kt

@@ -2,11 +2,17 @@ package com.y54895.matrixlib.api.hologram
 
 import org.bukkit.Location
 
+/**
+ * Anchor mode used when converting a logical hologram request to a rendered location.
+ */
 enum class MatrixHologramAnchor {
     EXACT,
     BLOCK_CENTER
 }
 
+/**
+ * Immutable hologram update request consumed by [MatrixHolograms].
+ */
 data class MatrixHologramRequest(
     val namespace: String,
     val id: String,
@@ -16,6 +22,9 @@ data class MatrixHologramRequest(
     val heightOverride: Double? = null
 ) {
 
+    /**
+     * Build the provider-facing hologram id.
+     */
     fun qualifiedId(): String {
         val resolvedNamespace = namespace.trim().ifBlank { "matrix" }.lowercase()
         return "${resolvedNamespace}_${id.trim()}"

src/main/kotlin/com/y54895/matrixlib/api/hologram/MatrixHolograms.kt

@@ -20,6 +20,10 @@ import taboolib.platform.BukkitPlugin
 import java.io.File
 import java.util.concurrent.ConcurrentHashMap
 
+/**
+ * Shared hologram bridge that picks one supported provider at runtime and keeps
+ * Matrix plugin requests synchronized with that provider.
+ */
 object MatrixHolograms {
 
     private const val resourcePath = "Hologram/config.yml"
@@ -63,17 +67,26 @@ object MatrixHolograms {
         requests.clear()
     }
 
+    /**
+     * Reload hologram settings and rebuild the active provider cache.
+     */
     fun reload() {
         settings = loadSettings()
         refreshAdapter(rebuildCached = true, force = true)
     }
 
+    /**
+     * Return the active hologram config file.
+     */
     fun configFile(): File {
         val plugin = BukkitPlugin.getInstance()
         MatrixResourceFiles.saveResourceIfAbsent(plugin, resourcePath)
         return MatrixResourceFiles.dataFile(plugin, resourcePath)
     }
 
+    /**
+     * Create or update a hologram request in the active provider.
+     */
     fun createOrUpdate(request: MatrixHologramRequest) {
         val qualifiedId = request.qualifiedId()
         if (request.lines.isEmpty()) {
@@ -85,12 +98,18 @@ object MatrixHolograms {
         adapter?.createOrUpdate(render(request))
     }
 
+    /**
+     * Remove a hologram by namespace and id.
+     */
     fun remove(namespace: String, id: String) {
         val qualifiedId = qualifiedId(namespace, id)
         requests.remove(qualifiedId)
         adapter?.remove(qualifiedId)
     }
 
+    /**
+     * Remove all holograms in a namespace.
+     */
     fun clearNamespace(namespace: String) {
         val prefix = "${namespace.trim().ifBlank { "matrix" }.lowercase()}_"
         val keys = requests.keys.filter { it.startsWith(prefix) }
@@ -100,10 +119,16 @@ object MatrixHolograms {
         }
     }
 
+    /**
+     * Return the configured default vertical offset.
+     */
     fun defaultHeight(): Double {
         return settings.defaultHeight
     }
 
+    /**
+     * Return the selected provider name or a status marker.
+     */
     fun providerSummary(): String {
         return if (!settings.enabled) {
             "disabled"
@@ -112,6 +137,9 @@ object MatrixHolograms {
         }
     }
 
+    /**
+     * Whether the hologram bridge is enabled in config.
+     */
     fun isEnabled(): Boolean {
         return settings.enabled
     }