Reworked config builder.

Added parameters' documentation.

README.md

@@ -1,5 +1,5 @@
 [![License (3-Clause BSD)](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg?style=flat-square)](https://opensource.org/licenses/BSD-3-Clause)
-[![Kotlin](https://img.shields.io/badge/kotlin-1.9.24-7f52ff)](https://kotlinlang.org/)
+[![Kotlin](https://img.shields.io/badge/kotlin-2.0.0-7f52ff)](https://kotlinlang.org/)
 [![bld](https://img.shields.io/badge/1.9.1-FA9052?label=bld&labelColor=2392FF)](https://rife2.com/bld)
 [![release](https://img.shields.io/github/release/ethauvin/isgd-shorten.svg)](https://github.com/ethauvin/isgd-shorten/releases/latest)
 [![Maven Central](https://img.shields.io/maven-central/v/net.thauvin.erik/isgd-shorten.svg?color=blue)](https://central.sonatype.com/artifact/net.thauvin.erik/isgd-shorten)

config/detekt/baseline.xml

@@ -5,6 +5,7 @@
     <ID>LongParameterList:Isgd.kt$Isgd.Companion$( url: String, shorturl: String = "", callback: String = "", logstats: Boolean = false, format: Format = Format.SIMPLE, isVgd: Boolean = false )</ID>
     <ID>MagicNumber:Isgd.kt$Isgd.Companion$200</ID>
     <ID>MagicNumber:Isgd.kt$Isgd.Companion$399</ID>
+    <ID>MaxLineLength:Isgd.kt$Isgd.Companion$*</ID>
     <ID>NestedBlockDepth:IsgdExample.kt$fun main(args: Array&lt;String&gt;)</ID>
     <ID>WildcardImport:IsgdTest.kt$import assertk.assertions.*</ID>
   </CurrentIssues>

examples/bld/lib/bld/bld-wrapper.properties

@@ -1,7 +1,7 @@
 bld.downloadExtensionJavadoc=false
 bld.downloadExtensionSources=true
 bld.extension-jacoco=com.uwyn.rife2:bld-jacoco-report:0.9.5
-bld.extensions=com.uwyn.rife2:bld-kotlin:0.9.4
+bld.extensions=com.uwyn.rife2:bld-kotlin:0.9.7
 bld.repositories=MAVEN_LOCAL,MAVEN_CENTRAL,RIFE2_SNAPSHOTS,RIFE2_RELEASES
 bld.downloadLocation=
 bld.sourceDirectories=

examples/bld/src/.idea/workspace.xml

@@ -1,8 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="PropertiesComponent">{
-  &quot;keyToString&quot;: {
-    &quot;settings.editor.selected.configurable&quot;: &quot;reference.settings.ide.settings.new.ui&quot;
-  }
-}</component>
-</project>

examples/bld/src/bld/java/com/example/ExampleBuild.java

@@ -24,7 +24,7 @@ public class ExampleBuild extends BaseProject {
         repositories = List.of(MAVEN_LOCAL, MAVEN_CENTRAL, SONATYPE_SNAPSHOTS_LEGACY);
 
         scope(compile)
-                .include(dependency("net.thauvin.erik:isgd-shorten:1.0.1"));
+                .include(dependency("net.thauvin.erik:isgd-shorten:1.0.2-SNAPSHOT"));
     }
 
     public static void main(String[] args) {

examples/gradle/build.gradle.kts

@@ -3,7 +3,7 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 plugins {
     id("application")
     id("com.github.ben-manes.versions") version "0.51.0"
-    kotlin("jvm") version "1.9.24"
+    kotlin("jvm") version "2.0.0"
 }
 
 repositories {
@@ -13,7 +13,7 @@ repositories {
 }
 
 dependencies {
-    implementation("net.thauvin.erik:isgd-shorten:1.0.1")
+    implementation("net.thauvin.erik:isgd-shorten:1.0.2-SNAPSHOT")
 }
 
 java {
@@ -25,11 +25,11 @@ application {
     mainClass.set("com.example.IsgdExampleKt")
 }
 
-tasks {
-    withType<KotlinCompile>().configureEach {
-        kotlinOptions.jvmTarget = java.targetCompatibility.toString()
-    }
+kotlin {
+    compilerOptions.jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)
+}
 
+tasks {
     register("runJava", JavaExec::class) {
         group = "application"
         mainClass.set("com.example.IsgdSample")

examples/gradle/settings.gradle.kts

@@ -7,4 +7,4 @@
  * in the user manual at https://docs.gradle.org/6.2/userguide/multi_project_builds.html
  */
 
-rootProject.name = "isgd-examples"
+rootProject.name = "isgd-shorten-examples-gradle"

lib/bld/bld-wrapper.properties

@@ -1,8 +1,8 @@
 bld.downloadExtensionJavadoc=false
 bld.downloadExtensionSources=true
 bld.extension-jacoco=com.uwyn.rife2:bld-jacoco-report:0.9.5
-bld.extensions=com.uwyn.rife2:bld-kotlin:0.9.4
-bld.extension-detekt=com.uwyn.rife2:bld-detekt:0.9.3
+bld.extensions=com.uwyn.rife2:bld-kotlin:0.9.7
+bld.extension-detekt=com.uwyn.rife2:bld-detekt:0.9.4
 bld.repositories=MAVEN_LOCAL,MAVEN_CENTRAL,RIFE2_SNAPSHOTS,RIFE2_RELEASES
 bld.downloadLocation=
 bld.sourceDirectories=

pom.xml

@@ -18,7 +18,7 @@
     <dependency>
       <groupId>org.jetbrains.kotlin</groupId>
       <artifactId>kotlin-stdlib</artifactId>
-      <version>1.9.24</version>
+      <version>2.0.0</version>
       <scope>compile</scope>
     </dependency>
     <dependency>

src/bld/java/net/thauvin/erik/IsgdShortenBuild.java

@@ -68,7 +68,7 @@ public class IsgdShortenBuild extends Project {
 
         repositories = List.of(MAVEN_LOCAL, MAVEN_CENTRAL);
 
-        final var kotlin = version(1, 9, 24);
+        final var kotlin = version(2, 0, 0);
         scope(compile)
                 .include(dependency("org.jetbrains.kotlin", "kotlin-stdlib", kotlin))
                 .include(dependency("net.thauvin.erik.urlencoder", "urlencoder-lib-jvm", version(1, 5, 0)));

src/main/kotlin/net/thauvin/erik/isgd/Config.kt

@@ -34,41 +34,83 @@ package net.thauvin.erik.isgd
 /**
  * Provides a builder to create/lookup an is.gd shortlink.
  */
-class Config private constructor(
-    val url: String,
-    val shorturl: String,
-    val callback: String,
-    val logstats: Boolean,
-    val format: Format,
-    val isVgd: Boolean
+class Config(
+    var url: String = "",
+    var shorturl: String = "",
+    var callback: String = "",
+    var logstats: Boolean = false,
+    var format: Format = Format.SIMPLE,
+    var isVgd: Boolean = false
 ) {
+    constructor(builder: Builder) : this() {
+        url = builder.url
+        shorturl = builder.shorturl
+        callback = builder.callback
+        logstats = builder.logstats
+        format = builder.format
+        isVgd = builder.isVgd
+    }
+
     /**
      * Configures the parameters to create/lookup an is.gd shortlink.
      *
-     * See the [is.gd API](https://is.gd/apishorteningreference.php).
+     * See the [is.gd Shortening](https://is.gd/apishorteningreference.php) or
+     * [is.gd Lookup](https://is.gd/apilookupreference.php) APIs.
      */
     data class Builder(
-        private var url: String = "",
-        private var shorturl: String = "",
-        private var callback: String = "",
-        private var logstats: Boolean = false,
-        private var format: Format = Format.SIMPLE,
-        private var isVgd: Boolean = false
+        var url: String = "",
+        var shorturl: String = "",
+        var callback: String = "",
+        var logstats: Boolean = false,
+        var format: Format = Format.SIMPLE,
+        var isVgd: Boolean = false
     ) {
-        fun url(url: String) = apply { this.url = url }
-        fun shortUrl(shortUrl: String) = apply { this.shorturl = shortUrl }
-        fun callback(callback: String) = apply { this.callback = callback }
-        fun logStats(logStats: Boolean) = apply { this.logstats = logStats }
-        fun format(format: Format) = apply { this.format = format }
-        fun isVgd(isVgd: Boolean) = apply { this.isVgd = isVgd }
+        /**
+         * The url parameter is the address that you want to shorten.
+         */
+        fun url(url: String): Builder = apply { this.url = url }
 
-        fun build() = Config(
-            url,
-            shorturl,
-            callback,
-            logstats,
-            format,
-            isVgd
-        )
+        /**
+         * You can specify the shorturl parameter if you'd like to pick a shortened URL instead of
+         * having is.gd randomly generate one. These must be between 5 and 30 characters long and can only contain
+         * alphanumeric characters and underscores. Shortened URLs are case sensitive. Bear in mind that a desired
+         * short URL might already be taken (this is very often the case with common words) so if you're using this
+         * option be prepared to respond to an error and get an alternative choice from your app's user.
+         */
+        fun shortUrl(shortUrl: String): Builder = apply { this.shorturl = shortUrl }
+
+        /**
+         * The callback parameter is used to specify a callback function to wrap the returned data in
+         * when using JSON format. This can be useful when working with cross domain data. Even when using JSON format
+         * this parameter is optional.
+         */
+        fun callback(callback: String): Builder = apply { this.callback = callback }
+
+        /**
+         * Turns on logging of detailed statistics when the shortened URL you create is accessed. This
+         * allows you to see how many times the link was accessed on a given day, what pages referred people to the
+         * link, what browser visitors were using etc. You can access these stats via the link preview page for your
+         * shortened URL (add a hyphen/dash to the end of the shortened URL to get to it). Creating links with
+         * statistics turned on has twice the "cost" towards our rate limit of other shortened links, so leave this
+         * parameter out of your API call if you don't require statistics on usage. See the
+         * [usage limits page](https://is.gd/usagelimits.php) for more information on this.
+         */
+        fun logStats(logStats: Boolean): Builder = apply { this.logstats = logStats }
+
+        /**
+         * The format parameter determines what format is.gd uses to send output back to you (e.g. to
+         * tell you what your new shortened URL is or if an error has occurred).
+         */
+        fun format(format: Format): Builder = apply { this.format = format }
+
+        /**
+         * Shorten using the `v.gd` domain.
+         */
+        fun isVgd(isVgd: Boolean): Builder = apply { this.isVgd = isVgd }
+
+        /**
+         * Builds a new configuration.
+         */
+        fun build() = Config(this)
     }
 }

src/main/kotlin/net/thauvin/erik/isgd/Isgd.kt

@@ -88,6 +88,16 @@ class Isgd private constructor() {
          * Lookup a shortlink.
          *
          * See the [is.gd API](https://is.gd/apilookupreference.php).
+         *
+         * @param The shorturl parameter is the shortened is.gd URL that you want to look up. You can either submit the
+         * full address (e.g. https://is.gd/example) or only the unique part (e.g. example). The address you submit
+         * should be properly formed; the API lookup function is not guaranteed to handle malformed URLs the same way as when you visit them manually.
+         * @param callback The callback parameter is used to specify a callback function to wrap the returned data in
+         * when using JSON format. This can be useful when working with cross domain data. Even when using JSON format
+         * this parameter is optional.
+         * @param format The format parameter determines what format is.gd uses to send output back to you (e.g. to
+         * tell you what your new shortened URL is or if an error has occurred).
+         * @param isVgd Lookup using the `v.gd` domain.
          */
         @JvmStatic
         @JvmOverloads
@@ -133,6 +143,26 @@ class Isgd private constructor() {
          * Shortens a link.
          *
          * See the [is.gd API](https://is.gd/apishorteningreference.php).
+         *
+         * @param url The url parameter is the address that you want to shorten.
+         * @param shorturl You can specify the shorturl parameter if you'd like to pick a shortened URL instead of
+         * having is.gd randomly generate one. These must be between 5 and 30 characters long and can only contain
+         * alphanumeric characters and underscores. Shortened URLs are case sensitive. Bear in mind that a desired
+         * short URL might already be taken (this is very often the case with common words) so if you're using this
+         * option be prepared to respond to an error and get an alternative choice from your app's user.
+         * @param callback The callback parameter is used to specify a callback function to wrap the returned data in
+         * when using JSON format. This can be useful when working with cross domain data. Even when using JSON format
+         * this parameter is optional.
+         * @param logstats Turns on logging of detailed statistics when the shortened URL you create is accessed. This
+         * allows you to see how many times the link was accessed on a given day, what pages referred people to the
+         * link, what browser visitors were using etc. You can access these stats via the link preview page for your
+         * shortened URL (add a hyphen/dash to the end of the shortened URL to get to it). Creating links with
+         * statistics turned on has twice the "cost" towards our rate limit of other shortened links, so leave this
+         * parameter out of your API call if you don't require statistics on usage. See the
+         * [usage limits page](https://is.gd/usagelimits.php) for more information on this.
+         * @param format The format parameter determines what format is.gd uses to send output back to you (e.g. to
+         * tell you what your new shortened URL is or if an error has occurred).
+         * @param isVgd Shorten using the `v.gd` domain.
          */
         @JvmStatic
         @JvmOverloads