From 77b62fc6dcaa682180af5a934d8f8e1a37d016ca Mon Sep 17 00:00:00 2001
From: "Erik C. Thauvin" <erik@thauvin.net>
Date: Wed, 5 Oct 2022 23:03:07 -0700
Subject: [PATCH] Improved KDoc

---
 .idea/compiler.xml                                 |  3 +++
 .../kotlin/net/thauvin/erik/jokeapi/JokeApi.kt     | 14 ++++++++------
 .../kotlin/net/thauvin/erik/jokeapi/JokeConfig.kt  |  4 ++--
 .../erik/jokeapi/exceptions/HttpErrorException.kt  |  2 +-
 .../erik/jokeapi/exceptions/JokeException.kt       |  2 +-
 .../net/thauvin/erik/jokeapi/models/Category.kt    |  4 +---
 .../kotlin/net/thauvin/erik/jokeapi/models/Flag.kt |  4 +---
 .../net/thauvin/erik/jokeapi/models/Format.kt      |  4 +---
 .../net/thauvin/erik/jokeapi/models/IdRange.kt     |  4 +---
 .../kotlin/net/thauvin/erik/jokeapi/models/Joke.kt |  2 +-
 .../net/thauvin/erik/jokeapi/models/Language.kt    |  4 +---
 .../net/thauvin/erik/jokeapi/models/Parameter.kt   |  4 +---
 .../kotlin/net/thauvin/erik/jokeapi/models/Type.kt |  4 +---
 13 files changed, 23 insertions(+), 32 deletions(-)

diff --git a/.idea/compiler.xml b/.idea/compiler.xml
index ecb5347..4703a78 100644
--- a/.idea/compiler.xml
+++ b/.idea/compiler.xml
@@ -2,6 +2,9 @@
 <project version="4">
   <component name="CompilerConfiguration">
     <bytecodeTargetLevel target="11">
+      <module name="examples" target="18" />
+      <module name="examples.main" target="18" />
+      <module name="examples.test" target="18" />
       <module name="jokeapi-examples.app" target="18" />
       <module name="jokeapi-examples.app.main" target="18" />
       <module name="jokeapi-examples.app.test" target="18" />
diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/JokeApi.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/JokeApi.kt
index b1e03cb..559682a 100644
--- a/src/main/kotlin/net/thauvin/erik/jokeapi/JokeApi.kt
+++ b/src/main/kotlin/net/thauvin/erik/jokeapi/JokeApi.kt
@@ -64,7 +64,7 @@ class JokeApi {
         val logger: Logger by lazy { Logger.getLogger(JokeApi::class.java.simpleName) }
 
         /**
-         * Use to make a direct API call.
+         * Makes a direct API call.
          *
          * Sse the [JokeAPI Documentation](https://jokeapi.dev/#endpoints) for more details.
          */
@@ -102,9 +102,10 @@ class JokeApi {
         }
 
         /**
-         * Use to retrieve a joke.
+         * Retrieves one or more jokes.
          *
          * Sse the [JokeAPI Documentation](https://jokeapi.dev/#joke-endpoint) for more details.
+         * @see [getJoke]
          */
         @JvmStatic
         @Throws(HttpErrorException::class, IOException::class)
@@ -184,7 +185,7 @@ class JokeApi {
         }
 
         /**
-         * Use to retrieve a joke using a [configuration][JokeConfig].
+         * Retrieves ond or more jokes using a [configuration][JokeConfig].
          *
          * Sse the [JokeAPI Documentation](https://jokeapi.dev/#joke-endpoint) for more details.
          */
@@ -284,11 +285,12 @@ class JokeApi {
         }
 
         /**
-         * Use to retrieve a [Joke].
+         * Retrieves a [Joke] instance.
          *
          * Sse the [JokeAPI Documentation](https://jokeapi.dev/#joke-endpoint) for more details.
          *
-         * @param splitNewLine Split newline within joke.
+         * @param splitNewLine Split newline within [Type.SINGLE] joke.
+         * @see [getRawJoke]
          */
         @JvmStatic
         @Throws(JokeException::class, HttpErrorException::class, IOException::class)
@@ -353,7 +355,7 @@ class JokeApi {
         }
 
         /**
-         * Use to retrieve a [Joke] using a [configuration][JokeConfig].
+         * Retrieves a [Joke] instance using a [configuration][JokeConfig].
          *
          * Sse the [JokeAPI Documentation](https://jokeapi.dev/#joke-endpoint) for more details.
          */
diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/JokeConfig.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/JokeConfig.kt
index a72b169..b64f502 100644
--- a/src/main/kotlin/net/thauvin/erik/jokeapi/JokeConfig.kt
+++ b/src/main/kotlin/net/thauvin/erik/jokeapi/JokeConfig.kt
@@ -57,11 +57,11 @@ class JokeConfig private constructor(
     val splitNewLine: Boolean,
 ) {
     /**
-     * Use to [build] a new configuration.
+     * [Builds][build] a new configuration.
      *
      * Sse the [JokeAPI Documentation](https://jokeapi.dev/#joke-endpoint) for more details.
      *
-     * @param splitNewLine Split newline within joke.
+     * @param splitNewLine Split newline within [Type.SINGLE] joke.
      */
     data class Builder(
         var categories: Set<Category> = setOf(Category.ANY),
diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/HttpErrorException.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/HttpErrorException.kt
index c332cc0..9f3b58b 100644
--- a/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/HttpErrorException.kt
+++ b/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/HttpErrorException.kt
@@ -35,7 +35,7 @@ package net.thauvin.erik.jokeapi.exceptions
 import java.io.IOException
 
 /**
- * Thrown whenever a server error occurs.
+ * Signals that a server error has occurred.
  *
  * Sse the [JokeAPI Documentation](https://jokeapi.dev/#status-codes) for more details.
  */
diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/JokeException.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/JokeException.kt
index eb75e7a..93bea1f 100644
--- a/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/JokeException.kt
+++ b/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/JokeException.kt
@@ -33,7 +33,7 @@
 package net.thauvin.erik.jokeapi.exceptions
 
 /**
- * Thrown whenever an error occurs.
+ * Signals that an error has occurred.
  *
  * Sse the [JokeAPI Documentation](https://jokeapi.dev/#errors) for more details.
  */
diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Category.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Category.kt
index 0d51bd2..86a766b 100644
--- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Category.kt
+++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Category.kt
@@ -33,9 +33,7 @@
 package net.thauvin.erik.jokeapi.models
 
 /**
- * The supported joke categories and aliases, use [ANY] for all.
- *
- * Sse the [JokeAPI Documentation](https://jokeapi.dev/#categories) for more details.
+ * The supported [categories and aliases](https://jokeapi.dev/#categories), use [ANY] for all.
  */
 enum class Category(val value: String) {
     ANY("Any"),
diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Flag.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Flag.kt
index 0447b90..c0e022e 100644
--- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Flag.kt
+++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Flag.kt
@@ -33,9 +33,7 @@
 package net.thauvin.erik.jokeapi.models
 
 /**
- * The supported blacklist flags, use [ALL] to prevent all.
- *
- * Sse the [JokeAPI Documentation](https://jokeapi.dev/#flags-param) for more details.
+ * The supported [blacklist flags](https://jokeapi.dev/#flags-param), use [ALL] to prevent all.
  */
 enum class Flag(val value: String) {
     NSFW("nsfw"),
diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Format.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Format.kt
index 405faa8..46ef81a 100644
--- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Format.kt
+++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Format.kt
@@ -33,9 +33,7 @@
 package net.thauvin.erik.jokeapi.models
 
 /**
- * The supported response formats.
- *
- * Sse the [JokeAPI Documentation](https://jokeapi.dev/#format-param) for more details.
+ * The supported response [formats](https://jokeapi.dev/#format-param).
  */
 enum class Format(val value: String) {
     JSON("json"), XML("xml"), YAML("yaml"), TEXT("txt"), TXT(TEXT.value)
diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/models/IdRange.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/models/IdRange.kt
index f18c902..bb6da9c 100644
--- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/IdRange.kt
+++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/IdRange.kt
@@ -33,8 +33,6 @@
 package net.thauvin.erik.jokeapi.models
 
 /**
- * Used to specify a joke's ID or range of IDs.
- *
- * Sse the [JokeAPI Documentation](https://jokeapi.dev/#idrange-param) for more details.
+ * Specifies a joke [ID or range of IDs](https://jokeapi.dev/#idrange-param).
  */
 data class IdRange(val start: Int = -1, val end: Int = -1)
diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Joke.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Joke.kt
index 16c35b9..3a5e1e1 100644
--- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Joke.kt
+++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Joke.kt
@@ -33,7 +33,7 @@
 package net.thauvin.erik.jokeapi.models
 
 /**
- * Used to store a joke's data.
+ * Stores a joke's data.
  */
 data class Joke(
     val error: Boolean,
diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Language.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Language.kt
index 781f8fe..1fce7a7 100644
--- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Language.kt
+++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Language.kt
@@ -33,9 +33,7 @@
 package net.thauvin.erik.jokeapi.models
 
 /**
- * The supported languages.
- *
- * Sse the [JokeAPI Documentation](https://jokeapi.dev/#lang) for more details.
+ * The supported [languages](https://jokeapi.dev/#lang).
  */
 enum class Language(val value: String) {
     ENGLISH("en"),
diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Parameter.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Parameter.kt
index f8f8c67..128c3ea 100644
--- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Parameter.kt
+++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Parameter.kt
@@ -33,9 +33,7 @@
 package net.thauvin.erik.jokeapi.models
 
 /**
- * The URL Parameters.
- *
- * Sse the [JokeAPI Documentation](https://jokeapi.dev/#url-parameters) for more details.
+ * The available [URL Parameters](https://jokeapi.dev/#url-parameters).
  */
 object Parameter {
     const val AMOUNT = "amount"
diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Type.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Type.kt
index 4dddcd7..9e28284 100644
--- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Type.kt
+++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Type.kt
@@ -33,9 +33,7 @@
 package net.thauvin.erik.jokeapi.models
 
 /**
- * The supported joke types, use [ALL] for all.
- *
- * Sse the [JokeAPI Documentation](https://jokeapi.dev/#type-param) for more details.
+ * The supported [types](https://jokeapi.dev/#type-param), use [ALL] for all.
  */
 enum class Type(val value: String) {
     SINGLE("single"),