From bfcbafc05a52da65b494c1da8dc1f9be21a5af0c Mon Sep 17 00:00:00 2001 From: "Erik C. Thauvin" Date: Wed, 5 Oct 2022 02:00:02 -0700 Subject: [PATCH] Added KDoc --- .../net/thauvin/erik/jokeapi/JokeApi.kt | 32 ++++++++++++++++++- .../net/thauvin/erik/jokeapi/JokeConfig.kt | 12 +++++++ .../jokeapi/exceptions/HttpErrorException.kt | 5 +++ .../erik/jokeapi/exceptions/JokeException.kt | 5 +++ .../thauvin/erik/jokeapi/models/Category.kt | 4 ++- .../net/thauvin/erik/jokeapi/models/Flag.kt | 4 ++- .../net/thauvin/erik/jokeapi/models/Format.kt | 4 ++- .../thauvin/erik/jokeapi/models/IdRange.kt | 5 +++ .../net/thauvin/erik/jokeapi/models/Joke.kt | 3 ++ .../thauvin/erik/jokeapi/models/Language.kt | 9 +++++- .../thauvin/erik/jokeapi/models/Parameter.kt | 6 ++++ .../net/thauvin/erik/jokeapi/models/Type.kt | 4 ++- 12 files changed, 87 insertions(+), 6 deletions(-) diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/JokeApi.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/JokeApi.kt index cc5ea74..b1e03cb 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/JokeApi.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/JokeApi.kt @@ -52,6 +52,9 @@ import java.util.logging.Level import java.util.logging.Logger import java.util.stream.Collectors +/** + * Implements the [JokeAPI](https://jokeapi.dev/). + */ class JokeApi { companion object { private const val API_URL = "https://v2.jokeapi.dev/" @@ -60,6 +63,11 @@ class JokeApi { @JvmStatic val logger: Logger by lazy { Logger.getLogger(JokeApi::class.java.simpleName) } + /** + * Use to make a direct API call. + * + * Sse the [JokeAPI Documentation](https://jokeapi.dev/#endpoints) for more details. + */ @JvmStatic @JvmOverloads @Throws(HttpErrorException::class, IOException::class) @@ -93,6 +101,11 @@ class JokeApi { return fetchUrl(urlBuilder.toString()) } + /** + * Use to retrieve a joke. + * + * Sse the [JokeAPI Documentation](https://jokeapi.dev/#joke-endpoint) for more details. + */ @JvmStatic @Throws(HttpErrorException::class, IOException::class) fun getRawJoke( @@ -170,6 +183,11 @@ class JokeApi { return apiCall(JOKE_ENDPOINT, path, params) } + /** + * Use to retrieve a joke using a [configuration][JokeConfig]. + * + * Sse the [JokeAPI Documentation](https://jokeapi.dev/#joke-endpoint) for more details. + */ @JvmStatic @Throws(HttpErrorException::class, IOException::class) fun getRawJoke(config: JokeConfig): String { @@ -194,7 +212,7 @@ class JokeApi { val connection = URL(url).openConnection() as HttpURLConnection connection.setRequestProperty( - "User-Agent", "Mozilla/5.0 (Linux x86_64; rv:104.0) Gecko/20100101 Firefox/104.0" + "User-Agent", "Mozilla/5.0 (Linux x86_64; rv:105.0) Gecko/20100101 Firefox/105.0" ) if (connection.responseCode in 200..399) { @@ -265,6 +283,13 @@ class JokeApi { return httpException } + /** + * Use to retrieve a [Joke]. + * + * Sse the [JokeAPI Documentation](https://jokeapi.dev/#joke-endpoint) for more details. + * + * @param splitNewLine Split newline within joke. + */ @JvmStatic @Throws(JokeException::class, HttpErrorException::class, IOException::class) fun getJoke( @@ -327,6 +352,11 @@ class JokeApi { } } + /** + * Use to retrieve a [Joke] using a [configuration][JokeConfig]. + * + * Sse the [JokeAPI Documentation](https://jokeapi.dev/#joke-endpoint) for more details. + */ @JvmStatic @Throws(JokeException::class, HttpErrorException::class, IOException::class) fun getJoke(config: JokeConfig): Joke { diff --git a/src/main/kotlin/net/thauvin/erik/jokeapi/JokeConfig.kt b/src/main/kotlin/net/thauvin/erik/jokeapi/JokeConfig.kt index 1461f32..a72b169 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/JokeConfig.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/JokeConfig.kt @@ -39,6 +39,11 @@ import net.thauvin.erik.jokeapi.models.IdRange import net.thauvin.erik.jokeapi.models.Language import net.thauvin.erik.jokeapi.models.Type +/** + * Joke Configuration. + * + * Use the [Builder] to create a new configuration. + */ class JokeConfig private constructor( val categories: Set, val language: Language, @@ -51,6 +56,13 @@ class JokeConfig private constructor( val safe: Boolean, val splitNewLine: Boolean, ) { + /** + * Use to [build] a new configuration. + * + * Sse the [JokeAPI Documentation](https://jokeapi.dev/#joke-endpoint) for more details. + * + * @param splitNewLine Split newline within joke. + */ data class Builder( var categories: Set = setOf(Category.ANY), var language: Language = Language.ENGLISH, 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 61107d5..c332cc0 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/HttpErrorException.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/HttpErrorException.kt @@ -34,6 +34,11 @@ package net.thauvin.erik.jokeapi.exceptions import java.io.IOException +/** + * Thrown whenever a server error occurs. + * + * Sse the [JokeAPI Documentation](https://jokeapi.dev/#status-codes) for more details. + */ class HttpErrorException @JvmOverloads constructor( val statusCode: Int, message: String, 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 5d13923..eb75e7a 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/JokeException.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/JokeException.kt @@ -32,6 +32,11 @@ package net.thauvin.erik.jokeapi.exceptions +/** + * Thrown whenever an error occurs. + * + * Sse the [JokeAPI Documentation](https://jokeapi.dev/#errors) for more details. + */ class JokeException @JvmOverloads constructor( val error: Boolean, val internalError: Boolean, 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 7262868..0d51bd2 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Category.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Category.kt @@ -33,7 +33,9 @@ package net.thauvin.erik.jokeapi.models /** - * Categories and aliases. + * The supported joke categories and aliases, use [ANY] for all. + * + * Sse the [JokeAPI Documentation](https://jokeapi.dev/#categories) for more details. */ 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 ab2d73e..0447b90 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Flag.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Flag.kt @@ -33,7 +33,9 @@ package net.thauvin.erik.jokeapi.models /** - * Blacklist flags. + * The supported blacklist flags, use [ALL] to prevent all. + * + * Sse the [JokeAPI Documentation](https://jokeapi.dev/#flags-param) for more details. */ 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 f0ac032..405faa8 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Format.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Format.kt @@ -33,7 +33,9 @@ package net.thauvin.erik.jokeapi.models /** - * Response formats. + * The supported response formats. + * + * Sse the [JokeAPI Documentation](https://jokeapi.dev/#format-param) for more details. */ 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 07dcaa4..f18c902 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/IdRange.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/IdRange.kt @@ -32,4 +32,9 @@ 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. + */ 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 72b1d39..16c35b9 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Joke.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Joke.kt @@ -32,6 +32,9 @@ package net.thauvin.erik.jokeapi.models +/** + * Used to store a joke's data. + */ data class Joke( val error: Boolean, val category: Category, 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 ec99251..781f8fe 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Language.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Language.kt @@ -33,19 +33,26 @@ package net.thauvin.erik.jokeapi.models /** - * Supported languages. + * The supported languages. + * + * Sse the [JokeAPI Documentation](https://jokeapi.dev/#lang) for more details. */ enum class Language(val value: String) { ENGLISH("en"), EN(ENGLISH.value), + CZECH("cs"), CS(CZECH.value), + GERMAN("de"), DE(GERMAN.value), + SPANISH("es"), ES(SPANISH.value), + FRENCH("fr"), FR(FRENCH.value), + PORTUGUESE("pt"), PT(PORTUGUESE.value) } 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 38e12bd..f8f8c67 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Parameter.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Parameter.kt @@ -32,6 +32,11 @@ package net.thauvin.erik.jokeapi.models +/** + * The URL Parameters. + * + * Sse the [JokeAPI Documentation](https://jokeapi.dev/#url-parameters) for more details. + */ object Parameter { const val AMOUNT = "amount" const val CONTAINS = "contains" @@ -45,4 +50,5 @@ object Parameter { const val BLACKLIST_FLAGS = FLAGS const val ID_RANGE = RANGE const val SAFE_MODE = SAFE + const val SEARCH = CONTAINS } 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 c21ce51..4dddcd7 100644 --- a/src/main/kotlin/net/thauvin/erik/jokeapi/models/Type.kt +++ b/src/main/kotlin/net/thauvin/erik/jokeapi/models/Type.kt @@ -33,7 +33,9 @@ package net.thauvin.erik.jokeapi.models /** - * Joke types. + * The supported joke types, use [ALL] for all. + * + * Sse the [JokeAPI Documentation](https://jokeapi.dev/#type-param) for more details. */ enum class Type(val value: String) { SINGLE("single"),