Improved KDoc

.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" />

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.
          */

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),

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.
  */

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.
  */

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"),

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"),

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)

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)

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,

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"),

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"

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"),