Add Dokka Documentation

Author: gmitch215

.github/workflows/build.yml

@@ -148,3 +148,24 @@ jobs:
           path: |
             build/libs/*.jar
 
+  dokka:
+    runs-on: ubuntu-latest
+    needs: [build, test]
+    name: Deploy Dokka
+    if: ${{ github.event_name != 'pull_request' && github.ref_name == 'master' }}
+    timeout-minutes: 30
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+          cache: 'gradle'
+      - name: Change Permissions
+        run: chmod +x ./gradlew
+      - name: Build Dokka
+        run: ./gradlew clean dokkaHtml
+      - name: Deploy Dokka
+        run: bash dokka.sh ${GITHUB_SHA::7}

build.gradle.kts

@@ -4,6 +4,7 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
     kotlin("jvm") version "2.0.20"
+    id("org.jetbrains.dokka") version "1.9.20"
     id("io.github.goooler.shadow") version "8.1.8"
 
     java
@@ -40,6 +41,10 @@ java {
 }
 
 tasks {
+    clean {
+        delete("bin")
+    }
+
     withType<KotlinCompile> {
         compilerOptions {
             jvmTarget.set(JvmTarget.JVM_17)

dokka.sh

@@ -0,0 +1,27 @@
+git config --local user.email "[email protected]"
+git config --local user.name "GitHub Action"
+git fetch origin gh-pages
+
+if [ ! -d "docs" ]; then
+  mkdir docs
+fi;
+
+cp -Rfv build/dokka/html/* ./docs/
+
+git switch -f gh-pages
+
+for dir in ./*
+do
+  if [ "$dir" == "./docs" ]; then
+    continue
+  fi
+
+  rm -rf "$dir"
+done
+
+cp -Rfv ./docs/* ./
+rm -rf ./docs
+
+git add .
+git commit -m "Update Dokka ($1)"
+git push -f origin gh-pages

src/main/kotlin/io/codemc/api/database/database.kt

@@ -10,17 +10,33 @@ private val config: DatabaseConfig = DatabaseConfig {
     defaultMaxAttempts = 5
 }
 
+/**
+ * The [DBConfig] instance.
+ */
 var dbConfig: DBConfig = DBConfig("", "", "")
 
+/**
+ * The MariaDB configuration.
+ * @param url The URl to the database.
+ * @param username The username into the database.
+ * @param password The password into the database.
+ */
 data class DBConfig(
     val url: String,
     val username: String,
     val password: String
 )
 
+/**
+ * Represents the database connection.
+ */
 lateinit var database: Database
     private set
 
+/**
+ * Attempts to connect to the database.
+ * @return The new [database] value
+ */
 fun connect(): Database {
     database = Database.connect(
         url = dbConfig.url,
@@ -32,6 +48,12 @@ fun connect(): Database {
     return database
 }
 
+/**
+ * Adds a user to the database.
+ * @param username The username of the jenkins user
+ * @param discord The Discord ID of the jenkins user
+ * @return The result of the `INSERT` statement.
+ */
 fun addUser(
     username: String,
     discord: Long
@@ -44,6 +66,11 @@ fun addUser(
     }
 }
 
+/**
+ * Gets a [User] by its jenkins username.
+ * @param username The username to lookup
+ * @return The user mapped to the jenkins username, or `null` if not found
+ */
 fun getUser(
     username: String
 ): User? = transaction(database) {
@@ -52,11 +79,21 @@ fun getUser(
         .firstOrNull()
 }
 
+/**
+ * Gets all users currently linked in the database.
+ * @return All users in the database
+ */
 fun getAllUsers(): List<User> = transaction(database) {
     Users.selectAll()
         .map { row -> User(row[Users.username], row[Users.discord]) }
 }
 
+/**
+ * Updates the user linked in the database.
+ * @param username The jenkins user to update
+ * @param discord The new Discord ID mapped to the user
+ * @return `1` if updated, else `0`
+ */
 fun updateUser(
     username: String,
     discord: Long
@@ -66,12 +103,21 @@ fun updateUser(
     }
 }
 
+/**
+ * Removes a user from the database.
+ * @param username The jenkins user to remove
+ * @return `1` if removed, else `0`
+ */
 fun removeUser(
     username: String
 ) = transaction(database) {
     Users.deleteWhere { Users.username eq username }
 }
 
+/**
+ * Removes all users from the database.
+ * @return The count of deleted members
+ */
 fun removeAllUsers() = transaction(database) {
     Users.deleteAll()
 }

src/main/kotlin/io/codemc/api/main.kt

@@ -9,6 +9,12 @@ import io.codemc.api.jenkins.jenkinsConfig
 import io.codemc.api.nexus.NexusConfig
 import io.codemc.api.nexus.nexusConfig
 
+/**
+ * Initializes the CodeMC API.
+ * @param jenkins The Jenkins configuration.
+ * @param nexus The Nexus configuration.
+ * @param db The database configuration.
+ */
 suspend fun initialize(
     jenkins: JenkinsConfig,
     nexus: NexusConfig,

src/main/kotlin/io/codemc/api/network.kt

@@ -12,7 +12,7 @@ import java.net.http.HttpResponse
 import java.nio.file.Files
 import java.time.Duration
 
-private const val USER_AGENT = "CodeMC Nexus API"
+private const val USER_AGENT = "CodeMC API"
 
 internal val http = HttpClient.newBuilder()
     .connectTimeout(Duration.ofSeconds(10))
@@ -23,7 +23,13 @@ internal val json = Json {
     explicitNulls = true
 }
 
-internal suspend fun req(url: String, request: HttpRequest.Builder.() -> Unit = { GET() }): HttpResponse<String>
+/**
+ * Sends an HTTP request using the HTTP Client.
+ * @param url The URL to send the request to.
+ * @param request The builder modifier on the HTTP Request.
+ * @return An HTTP Response.
+ */
+suspend fun req(url: String, request: HttpRequest.Builder.() -> Unit = { GET() }): HttpResponse<String>
     = withContext(Dispatchers.IO) {
     val req = HttpRequest.newBuilder()
         .uri(URI.create(url))
@@ -34,13 +40,19 @@ internal suspend fun req(url: String, request: HttpRequest.Builder.() -> Unit =
     http.send(req.build(), HttpResponse.BodyHandlers.ofString())
 }
 
-suspend fun filesExists(url: String, files: Iterable<String>): Boolean = withContext(Dispatchers.IO) {
+/**
+ * Checks if any file exist in a Git Repository.
+ * @param git The URL to the git repository.
+ * @param files The files to check if they exist, relative to the repository.
+ * @return `true` if **any** file exists in the git repository, `false` if none exist.
+ */
+suspend fun filesExists(git: String, files: Iterable<String>): Boolean = withContext(Dispatchers.IO) {
     val dir = Files.createTempDirectory("codemc")
 
     Runtime.getRuntime().exec(arrayOf(
         "git",
         "clone",
-        url,
+        git,
         dir.toString()
     )).waitFor()
 

src/main/kotlin/io/codemc/api/nexus/endpoints.kt

@@ -8,6 +8,11 @@ import kotlinx.serialization.json.putJsonObject
 
 // Fields
 
+/**
+ * The Root API URl for the Nexus instance.
+ *
+ * Usually `https://<nexus-url>/service/rest/v1`.
+ */
 val API_URL
     get() = "${nexusConfig.url}/service/rest/v1"