Change some docs and README, PastebinClient constructors

Author: mrapplexz

README.MD

@@ -49,4 +49,18 @@ Multiplatform Kotlin library to interact with the pastebin.com API.
  implementation("net.pearx.kpastebin:kpastebin-PLATFORM_YOU_WANT:$kpastebinVersion") // for Native
 ```
 
-2. Use the library and have fun!
+2. Add [kotlinx.coroutines](https://github.com/Kotlin/kotlinx.coroutines) and any [Ktor client engine](https://ktor.io/clients/http-client/engines.html) to your project's dependencies.
+
+3. Use the library and have fun! See [net.pearx.kpastebin.PastebinClient](src/commonMain/kotlin/net/pearx/kpastebin/PastebinClient.kt) class KDoc for more info.
+
+# Examples
+```kotlin
+runBlocking {
+    // see KDoc for more info
+    val client = PastebinClient("your dev key") // create a PastebinClient instance. You can get your dev key here: https://pastebin.com/doc_api#1
+    client.getPaste("0b42rwhf") // getting a paste
+    
+    client.login("username", "password") // logging in
+    client.getUserDetails().accountType // getting current user account type
+}
+```

src/commonMain/kotlin/net/pearx/kpastebin/PastebinClient.kt

@@ -8,7 +8,9 @@
 package net.pearx.kpastebin
 
 import io.ktor.client.HttpClient
+import io.ktor.client.HttpClientConfig
 import io.ktor.client.engine.HttpClientEngine
+import io.ktor.client.engine.HttpClientEngineFactory
 import io.ktor.client.features.ClientRequestException
 import io.ktor.client.features.HttpResponseValidator
 import io.ktor.client.features.RedirectResponseException
@@ -26,30 +28,37 @@ import net.pearx.kpastebin.model.UserDetails
  * Pastebin API client with specified unique developer API key.
  * You can get your key on [official Pastebin website](https://pastebin.com/doc_api#1).
  *
- * @param engine Ktor [HttpClientEngine] to use
- * @param devKey Unique developer API key
- * @param userKey user key used for requests. Use null for guest user.
+ * @property devKey Unique developer API key
+ * @property engine Ktor [HttpClientEngine] to use. Use null to detect it automatically.
+ * @property userKey User key used for requests. Use null for guest user. It also can be set using [login] method.
  */
 public class PastebinClient(
-    private val engine: HttpClientEngine,
     private val devKey: String,
-    /**
-     * User key used for requests. Use null for guest user. It also can be set using [login] method.
-     */
+    private val engine: HttpClientEngine? = null,
     public var userKey: String? = null
 ) {
-    private val http = HttpClient(engine) {
-        HttpResponseValidator { // https://youtrack.jetbrains.com/issue/KTOR-406
-            validateResponse { response ->
-                when (response.status.value) {
-                    in 300..399 -> throw RedirectResponseException(response)
-                    in 400..499 -> throw ClientRequestException(response)
-                    in 500..599 -> throw ServerResponseException(response)
+    /**
+     * Constructs a new [PastebinClient] instance using specified [engine], [devKey] and [userKey].
+     * @see PastebinClient
+     */
+    public constructor(devKey: String, engine: HttpClientEngineFactory<*>, userKey: String? = null): this(devKey, engine.create(), userKey)
+
+    private val http: HttpClient
+    init {
+        val config: HttpClientConfig<*>.() -> Unit = {
+            HttpResponseValidator { // https://youtrack.jetbrains.com/issue/KTOR-406
+                validateResponse { response ->
+                    when (response.status.value) {
+                        in 300..399 -> throw RedirectResponseException(response)
+                        in 400..499 -> throw ClientRequestException(response)
+                        in 500..599 -> throw ServerResponseException(response)
+                    }
                 }
             }
-        }
 
-        expectSuccess = false
+            expectSuccess = false
+        }
+        http = if(engine == null) HttpClient(config) else HttpClient(engine, config)
     }
 
     private suspend fun sendRequest(url: String, userKeyRequired: Boolean, userKey: String?, parameters: Parameters): String {

src/commonMain/kotlin/net/pearx/kpastebin/model/AccountType.kt

@@ -16,4 +16,4 @@ public enum class AccountType {
 
     /** Paid pro account. */
     PRO;
-}
+}

src/commonMain/kotlin/net/pearx/kpastebin/model/PasteDetails.kt

@@ -12,27 +12,27 @@ import net.pearx.kpastebin.internal.XML_PROPERTY_REGEX
 
 /**
  * A detailed Pastebin paste information.
+ * @property key Paste key.
+ * @property date Paste publication date in Unix time format.
+ * @property title Paste title.
+ * @property size Paste size in bytes.
+ * @property expireDate Paste expiration date in Unix time format.
+ * @property privacy Paste privacy status.
+ * @property formatLong Paste syntax highlighting language in a user-readable format (e.g., Kotlin or C#).
+ * @property formatShort Paste syntax highlighting language in a short format (e.g. kotlin or csharp).
+ * @property url Paste URL.
+ * @property hits Paste view count.
  */
 public data class PasteDetails(
-    /** Paste key. */
     val key: String,
-    /** Paste publication date in Unix time format. */
     val date: ULong,
-    /** Paste title. */
     val title: String,
-    /** Paste size in bytes. */
     val size: Int,
-    /** Paste expiration date in Unix time format. */
     val expireDate: ULong,
-    /** Paste privacy status. */
     val privacy: Privacy,
-    /** Paste syntax highlighting language in a user-readable format (e.g., Kotlin or C#). */
     val formatLong: String,
-    /** Paste syntax highlighting language in a short format (e.g. kotlin or csharp). */
     val formatShort: String,
-    /** Paste URL. */
     val url: String,
-    /** Paste view count. */
     val hits: Int
 ) {
     internal companion object {

src/commonMain/kotlin/net/pearx/kpastebin/model/UserDetails.kt

@@ -12,25 +12,25 @@ import net.pearx.kpastebin.internal.XML_PROPERTY_REGEX
 
 /**
  * A detailed Pastebin user information.
+ * @property name Full user name.
+ * @property defaultFormatShort Default paste syntax highlighting language for this user in a short format (e.g., kotlin or csharp).
+ * @property defaultExpiration Default paste expiration duration for this user.
+ * @property avatarUrl User avatar URL.
+ * @property defaultPrivacy Default paste privacy status for this user.
+ * @property website User website.
+ * @property email User E-Mail.
+ * @property location User location.
+ * @property accountType User account type.
  */
 public data class UserDetails(
-    /** Full user name. */
     val name: String,
-    /** Default paste syntax highlighting language for this user in a short format (e.g., kotlin or csharp). */
     val defaultFormatShort: String,
-    /** Default paste expiration duration for this user. */
     val defaultExpiration: ExpireDate,
-    /** User avatar URL. */
     val avatarUrl: String,
-    /** Default paste privacy status for this user. */
     val defaultPrivacy: Privacy,
-    /** User website. */
     val website: String,
-    /** User E-Mail. */
     val email: String,
-    /** User location. */
     val location: String,
-    /** User account type. */
     val accountType: AccountType
 ) {
     internal companion object {