add documentation

Author: zp4rker

build.gradle.kts

@@ -1,6 +1,7 @@
 plugins {
     kotlin("jvm") version "2.0.21"
     kotlin("plugin.serialization") version "2.0.21"
+    id("org.jetbrains.dokka") version "1.9.20"
 
     id("com.gradleup.shadow") version "8.3.3"
 

src/main/kotlin/com/zp4rker/bukkot/builders/item/EnchantNode.kt

@@ -3,7 +3,7 @@ package com.zp4rker.bukkot.builders.item
 import org.bukkit.enchantments.Enchantment
 
 /**
- * @author zp4rker
+ * Node for [org.bukkit.inventory.ItemStack] enchantments
  */
 class EnchantNode {
     val set = mutableSetOf<EnchantContainer>()

src/main/kotlin/com/zp4rker/bukkot/builders/item/ItemAttributes.kt

@@ -6,7 +6,7 @@ import org.bukkit.attribute.Attribute
 import org.bukkit.attribute.AttributeModifier
 
 /**
- * @author zp4rker
+ * Attributes for [org.bukkit.inventory.ItemStack]
  */
 class ItemAttributes {
     val modifiers: Multimap<Attribute, AttributeModifier> = ArrayListMultimap.create()

src/main/kotlin/com/zp4rker/bukkot/builders/item/ItemBuilder.kt

@@ -12,23 +12,46 @@ import org.bukkit.inventory.ItemStack
 import org.bukkit.inventory.meta.ItemMeta
 
 /**
- * @author zp4rker
+ * Creates a customised [ItemStack]
+ *
+ * @param type material of the itemstack
+ * @param data customisations of itemstack
  */
 fun item(type: Material, data: ItemStack.() -> Unit) = ItemStack(type).apply(data)
 
+/**
+ * Customises an [ItemStack]
+ *
+ * @param base the itemstack to start off with
+ * @see item
+ */
 fun item(base: ItemStack, data: ItemStack.() -> Unit) = ItemStack(base).apply(data)
 
+/**
+ * Apply changes to [ItemMeta]
+ *
+ * @param data the meta to apply
+ */
 fun <T : ItemMeta> ItemStack.meta(data: T.() -> Unit) {
     val meta = itemMeta(type, data)
     itemMeta = meta
 }
 
+/**
+ * Customised [ItemMeta] for type
+ *
+ * @param type material to generate meta for
+ * @param data the meta to apply
+ */
 @Suppress("UNCHECKED_CAST")
 fun <T : ItemMeta> itemMeta(type: Material, data: T.() -> Unit) = Bukkit.getItemFactory().getItemMeta(type)
     .let { it as? T }
     ?.apply(data)
     ?: throw IllegalArgumentException("Invalid ItemMeta for specified material.")
 
+/**
+ * [ItemMeta] lore lines as combined string in [net.kyori.adventure.text.minimessage.MiniMessage] format
+ */
 var ItemMeta.loreString: String?
     get() = lore()?.joinToString("\n") { it.minimessage() }
     set(value) {
@@ -37,9 +60,15 @@ var ItemMeta.loreString: String?
         }
     }
 
+/**
+ * [ItemMeta] lore lines in plain text
+ */
 val ItemMeta.plainLore: List<String>?
     get() = lore()?.map { it.plain() }
 
+/**
+ * [ItemMeta] lore lines in plain text as combined string
+ */
 val ItemMeta.plainLoreString: String?
     get() = plainLore?.joinToString("\n")
 
@@ -61,6 +90,11 @@ var ItemMeta.unbreakable: Boolean
 
 fun ItemMeta.flag(vararg flags: ItemFlag) = addItemFlags(*flags)
 
+/**
+ * Add [ItemAttributes] to [ItemMeta]
+ *
+ * @param data the attributes to apply
+ */
 fun ItemMeta.attributes(data: ItemAttributes.() -> Unit) {
     val attributes = ItemAttributes().apply(data)
     val mods = attributes.modifiers
@@ -71,6 +105,12 @@ fun ItemMeta.attributes(data: ItemAttributes.() -> Unit) {
             }
 }
 
+/**
+ * Add enchants to [ItemMeta]
+ *
+ * @param unsafe bypass level restriction
+ * @param data the enchants to apply
+ */
 fun ItemMeta.enchant(unsafe: Boolean = false, data: EnchantNode.() -> Unit) {
     EnchantNode().apply(data).set.forEach {
         addEnchant(it.enchantment, it.level, unsafe)

src/main/kotlin/com/zp4rker/bukkot/extensions/Component.kt

@@ -6,9 +6,21 @@ import net.kyori.adventure.text.serializer.legacy.LegacyComponentSerializer
 import net.kyori.adventure.text.serializer.plain.PlainTextComponentSerializer
 
 /**
- * @author zp4rker
+ * Convert to legacy Minecraft string (i.e. "§3Test")
  */
 fun Component.legacy() = LegacyComponentSerializer.legacySection().serialize(this)
+
+/**
+ * Convert to json string
+ */
 fun Component.json() = JSONComponentSerializer.json().serialize(this)
+
+/**
+ * Convert to plain text. All formatting stripped
+ */
 fun Component.plain() = PlainTextComponentSerializer.plainText().serialize(this)
+
+/**
+ * Convert to minimessage format (i.e. "<gold>Hello!</gold>")
+ */
 fun Component.minimessage() = MM.serialize(this)

src/main/kotlin/com/zp4rker/bukkot/extensions/Constants.kt

@@ -6,9 +6,12 @@ import org.bukkit.Server
 import org.bukkit.plugin.PluginManager
 
 /**
- * @author zp4rker
+ * The server plugin manager
  */
 object PMANAGER : PluginManager by Bukkit.getPluginManager()
 object SERVER : Server by Bukkit.getServer()
 
+/**
+ * Instance of [MiniMessage]
+ */
 val MM = MiniMessage.miniMessage()

src/main/kotlin/com/zp4rker/bukkot/extensions/Listener.kt

@@ -5,12 +5,17 @@ import org.bukkit.event.Listener
 import org.bukkit.plugin.java.JavaPlugin
 
 /**
- * @author zp4rker
+ * Registers listener by plugin
+ *
+ * @param plugin the plugin to register the listener
  */
 fun Listener.register(plugin: JavaPlugin) {
     PMANAGER.registerEvents(this, plugin)
 }
 
+/**
+ * Unregisters a listener
+ */
 fun Listener.unregister() {
     HandlerList.unregisterAll(this)
 }

src/main/kotlin/com/zp4rker/bukkot/extensions/Plugin.kt

@@ -5,7 +5,14 @@ import org.bukkit.scheduler.BukkitRunnable
 import org.bukkit.scheduler.BukkitTask
 
 /**
- * @author zp4rker
+ * Run a regular [BukkitRunnable]
+ *
+ * @param delay ticks before task runs. Set to 0 to run immediately
+ * @param async whether or not to run in async
+ * @param task the task to run in the [BukkitRunnable]
+ *
+ * @see BukkitRunnable.runTask
+ * @see BukkitRunnable.runTaskLater
  */
 fun Plugin.runTask(delay: Long = 0, async: Boolean = false, task: BukkitRunnable.() -> Unit): BukkitTask {
     return if (delay > 0) {
@@ -23,6 +30,14 @@ fun Plugin.runTask(delay: Long = 0, async: Boolean = false, task: BukkitRunnable
     }
 }
 
+/**
+ * Run a timer [BukkitRunnable]
+ *
+ * @param period ticks between runs
+ *
+ * @see runTask
+ * @see BukkitRunnable.runTaskTimer
+ */
 fun Plugin.runTaskTimer(
     delay: Long = 0,
     period: Long = 20,
@@ -36,6 +51,15 @@ fun Plugin.runTaskTimer(
     }
 }
 
+/**
+ * Run a timer [BukkitRunnable] limited amount of times
+ *
+ * @param repeat amount of times to repeat task. Specified as range (useful for using within task)
+ * @param task the task to run in the [BukkitRunnable]. Has access to repeat number
+ *
+ * @see IntProgression
+ * @see runTaskTimer
+ */
 fun Plugin.repeatTask(
     repeat: IntProgression,
     delay: Long = 0,
@@ -59,6 +83,9 @@ fun Plugin.repeatTask(
     }
 }
 
+/**
+ * Class to simplify [BukkitRunnable] lambdas
+ */
 internal class LambdaRunnable(private val task: BukkitRunnable.() -> Unit) : BukkitRunnable() {
     override fun run() {
         task()

src/main/kotlin/com/zp4rker/bukkot/extensions/String.kt

@@ -5,10 +5,28 @@ import net.kyori.adventure.text.Component
 import org.bukkit.ChatColor
 
 /**
- * @author zp4rker
+ * Colours a legacy Minecraft string (i.e. "&3Test")
+ */
+fun String.colourify(char: Char = '&') = ChatColor.translateAlternateColorCodes(char, this)
+
+/**
+ * For the Americans
+ *
+ * @see colourify
+ */
+fun String.colorify(char: Char = '&') = colourify(char)
+
+/**
+ * Strip colours from string
  */
-fun String.colorify(char: Char = '&') = ChatColor.translateAlternateColorCodes(char, this)
 fun String.stripColors() = ChatColor.stripColor(this)
 
+/**
+ * Convert plain text to [Component] for use in Paper
+ */
 fun String.component() = Component.text(this)
+
+/**
+ * Convert [net.kyori.adventure.text.minimessage.MiniMessage] format to [Component]
+ */
 fun String.minimessage() = MM.deserialize(this)

src/main/kotlin/com/zp4rker/bukkot/extensions/TimeUnit.kt

@@ -3,7 +3,7 @@ package com.zp4rker.bukkot.extensions
 import java.util.concurrent.TimeUnit
 
 /**
- * @author zp4rker
+ * Convert time units to ticks
  */
 fun TimeUnit.toTicks(d: Long): Long {
     return when (this) {
@@ -23,6 +23,9 @@ fun TimeUnit.toTicks(d: Long): Long {
     }
 }
 
+/**
+ * [TimeUnit] for ticks
+ */
 object TickTimeUnit {
     fun toNanos(ticks: Long) = ticks * 50000000
     fun toMicros(ticks: Long) = ticks * 50000

src/main/kotlin/com/zp4rker/bukkot/listener/Anonymous.kt

@@ -8,16 +8,33 @@ import org.bukkit.plugin.EventExecutor
 import org.bukkit.plugin.Plugin
 
 /**
- * @author zp4rker
+ * Interface for anonymous listeners
+ * @see listener
  */
 interface AnonymousListener<T : Event> : Listener {
     fun onEvent(event: T)
 }
 
+/**
+ * Creates an instance of [AnonymousListener]
+ *
+ * @param action the function to be executed in the listener
+ * @return an instance of [AnonymousListener]
+ * @see register
+ */
 inline fun <T : Event> listener(crossinline action: AnonymousListener<T>.(T) -> Unit) = object : AnonymousListener<T> {
     override fun onEvent(event: T) = action(event)
 }
 
+/**
+ * Registers an [AnonymousListener]. Parameters derived from [org.bukkit.event.EventHandler]
+ *
+ * @param plugin the plugin registering the listener
+ * @param priority the listener priority
+ * @param ignoreCancelled whether the listener should still trigger for cancelled events
+ *
+ * @see [com.zp4rker.bukkot.extensions.unregister]
+ */
 inline fun <reified T : Event> AnonymousListener<T>.register(
     plugin: Plugin,
     priority: EventPriority = EventPriority.NORMAL,

src/main/kotlin/com/zp4rker/bukkot/listener/Inline.kt

@@ -8,11 +8,17 @@ import java.util.concurrent.Executors
 import java.util.concurrent.ScheduledExecutorService
 import java.util.concurrent.TimeUnit
 
-/**
- * @author zp4rker
- */
 typealias Predicate<T> = (T) -> Boolean
 
+/**
+ * Register a continuous listener
+ *
+ * @param T the event to listen to
+ * @param predicate function to determine pre-requisites for listener to invoke action
+ * @param priority the listener priority
+ * @param ignoreCancelled whether the listener should still trigger for cancelled events
+ * @param action the function to be executed in the listener
+ */
 inline fun <reified T : Event> Plugin.on(
     crossinline predicate: Predicate<T> = { true },
     priority: EventPriority = EventPriority.NORMAL,
@@ -26,6 +32,16 @@ inline fun <reified T : Event> Plugin.on(
 
 val scheduler: ScheduledExecutorService = Executors.newSingleThreadScheduledExecutor()
 
+/**
+ * Register a limited listener
+ *
+ * @param T the event to listen to
+ * @param amount amount of times this listener should listen for event
+ * @param timeout milliseconds before listener times out even if [amount] has not been reached. Set to 0 for no timeout
+ * @param timeoutAction the function to run when the listener times out
+ *
+ * @see on
+ */
 inline fun <reified T : Event> Plugin.expect(
     crossinline predicate: Predicate<T> = { true },
     amount: Int = 1,