Fixes all missing public documentation in commonMain (#12)

* Fixes all missing public documentation in commonMain.

* Activates detekt `comments` rules.

config/detekt/detekt.yml

@@ -51,7 +51,7 @@ output-reports:
   # - 'SarifOutputReport'
 
 comments:
-  active: false
+  active: true
   AbsentOrWrongFileLicense:
     active: false
     licenseTemplateFile: 'license.template'

core/src/commonMain/kotlin/io/shortway/kobankat/CacheFetchPolicy.kt

@@ -30,6 +30,9 @@ public expect enum class CacheFetchPolicy {
     ;
 
     public companion object {
+        /**
+         * Returns the default policy when no policy is provided.
+         */
         public fun default(): CacheFetchPolicy
     }
 }

core/src/commonMain/kotlin/io/shortway/kobankat/DangerousSettings.kt

@@ -1,5 +1,14 @@
 package io.shortway.kobankat
 
+/**
+ * Only use a Dangerous Setting if suggested by RevenueCat support team.
+ */
 public data class DangerousSettings(
+    /**
+     * Disable or enable syncing purchases automatically. If this is disabled, RevenueCat will not
+     * sync any purchase automatically, and you will have to call [syncPurchases] whenever a new
+     * purchase is completed in order to send it to the RevenueCat's backend. Auto syncing of
+     * purchases is enabled by default.
+     */
     public val autoSyncPurchases: Boolean,
 )

core/src/commonMain/kotlin/io/shortway/kobankat/EntitlementInfo.kt

@@ -1,27 +1,92 @@
 package io.shortway.kobankat
 
+/**
+ * This object gives you access to all of the information about the status of a user's entitlements.
+ */
 public expect class EntitlementInfo
 
+/**
+ * The entitlement identifier configured in the RevenueCat dashboard.
+ */
 public expect val EntitlementInfo.identifier: String
+
+/**
+ * True if the user has access to this entitlement.
+ */
 public expect val EntitlementInfo.isActive: Boolean
+
+/**
+ * True if the underlying subscription is set to renew at the end of the billing period
+ * (expirationDate). Will always be True if entitlement is for lifetime access.
+ */
 public expect val EntitlementInfo.willRenew: Boolean
+
+/**
+ * The last period type this entitlement was in.
+ */
 public expect val EntitlementInfo.periodType: PeriodType
+
 /**
- * Nullable on iOS only not on Android.
+ * Nullable on iOS only not on Android. The latest purchase or renewal date for the entitlement,
+ * in millis since the Unix epoch.
  */
 public expect val EntitlementInfo.latestPurchaseDateMillis: Long?
+
 /**
- * Nullable on iOS only not on Android.
+ * Nullable on iOS only not on Android. The first date this entitlement was purchased in millis
+ * since the Unix epoch.
  */
 public expect val EntitlementInfo.originalPurchaseDateMillis: Long?
+
+/**
+ * The expiration date for the entitlement, can be `null` for lifetime access. If the [periodType]
+ * is [PeriodType.TRIAL], this is the trial expiration date.
+ */
 public expect val EntitlementInfo.expirationDateMillis: Long?
+
+/**
+ * The store where this entitlement was unlocked from.
+ */
 public expect val EntitlementInfo.store: Store
+
+/**
+ * The product identifier that unlocked this entitlement.
+ *  * For Google subscriptions, this is the subscription ID.
+ *  * For Amazon subscriptions, this is the `termSku`.
+ *  * For INAPP purchases, this is simply the `productId`.
+ */
 public expect val EntitlementInfo.productIdentifier: String
+
+/**
+ * Play Store only. The base plan identifier that unlocked this entitlement.
+ */
 public expect val EntitlementInfo.productPlanIdentifier: String?
+
+/**
+ * False if this entitlement is unlocked via a production purchase.
+ */
 public expect val EntitlementInfo.isSandbox: Boolean
+
+/**
+ * The date an unsubscribe was detected. Can be `null`.
+ *
+ * Note: Entitlement may still be active even if user has unsubscribed. Check the [isActive]
+ * property.
+ */
 public expect val EntitlementInfo.unsubscribeDetectedAtMillis: Long?
+
+/**
+ * The date a billing issue was detected in millis since the Unix epoch. Can be `null` if there is
+ * no billing issue or an issue has been resolved. Note: Entitlement may still be active even if
+ * there is a billing issue. Check the `isActive` property.
+ */
 public expect val EntitlementInfo.billingIssueDetectedAtMillis: Long?
 public expect val EntitlementInfo.ownershipType: OwnershipType
+
+/**
+ * If entitlement verification was enabled, the result of that verification. If not,
+ * [VerificationResult.NOT_REQUESTED].
+ */
 public expect val EntitlementInfo.verification: VerificationResult
 
 /**

core/src/commonMain/kotlin/io/shortway/kobankat/EntitlementInfos.kt

@@ -1,8 +1,20 @@
 package io.shortway.kobankat
 
+/**
+ * This class contains all the entitlements associated to the user.
+ */
 public expect class EntitlementInfos
 
+/**
+ * Map of all EntitlementInfo [EntitlementInfo] objects (active and inactive) keyed by entitlement
+ * identifier.
+ */
 public expect val EntitlementInfos.all: Map<String, EntitlementInfo>
+
+/**
+ * If entitlement verification was enabled, the result of that verification. If not,
+ * [VerificationResult.NOT_REQUESTED].
+ */
 public expect val EntitlementInfos.verification: VerificationResult
 
 /**

core/src/commonMain/kotlin/io/shortway/kobankat/EntitlementVerificationMode.kt

@@ -1,6 +1,16 @@
 package io.shortway.kobankat
 
+/**
+ * Verification strictness levels for [EntitlementInfo].
+ */
 public enum class EntitlementVerificationMode {
+    /**
+     * The SDK will not perform any entitlement verification.
+     */
     DISABLED,
+
+    /**
+     * Enable entitlement verification.
+     */
     INFORMATIONAL,
 }

core/src/commonMain/kotlin/io/shortway/kobankat/LogHandler.kt

@@ -6,9 +6,28 @@ package io.shortway.kobankat
  * @see PurchasesFactory.logHandler
  */
 public expect interface LogHandler {
+    /**
+     * Log a message at the [LogLevel.VERBOSE] level.
+     */
     public fun v(tag: String, msg: String)
+
+    /**
+     * Log a message at the [LogLevel.DEBUG] level.
+     */
     public fun d(tag: String, msg: String)
+
+    /**
+     * Log a message at the [LogLevel.INFO] level.
+     */
     public fun i(tag: String, msg: String)
+
+    /**
+     * Log a message at the [LogLevel.WARN] level.
+     */
     public fun w(tag: String, msg: String)
+
+    /**
+     * Log a message at the [LogLevel.ERROR] level.
+     */
     public fun e(tag: String, msg: String, throwable: Throwable?)
 }

core/src/commonMain/kotlin/io/shortway/kobankat/LogLevel.kt

@@ -1,5 +1,8 @@
 package io.shortway.kobankat
 
+/**
+ * The level to log at.
+ */
 public expect enum class LogLevel {
     VERBOSE,
     DEBUG,

core/src/commonMain/kotlin/io/shortway/kobankat/ProductType.kt

@@ -1,7 +1,21 @@
 package io.shortway.kobankat
 
+/**
+ * Possible product types.
+ */
 public expect enum class ProductType {
+    /**
+     * A subscription product.
+     */
     SUBS,
+
+    /**
+     * An in-app purchase product.
+     */
     INAPP,
+
+    /**
+     * The product type could not be determined.
+     */
     UNKNOWN,
 }

core/src/commonMain/kotlin/io/shortway/kobankat/PurchasesConfiguration.kt

@@ -1,5 +1,8 @@
 package io.shortway.kobankat
 
+/**
+ * Configuration of the SDK.
+ */
 public data class PurchasesConfiguration(
     internal val apiKey: String,
     internal val appUserId: String,

core/src/commonMain/kotlin/io/shortway/kobankat/PurchasesDelegate.kt

@@ -3,6 +3,10 @@ package io.shortway.kobankat
 import io.shortway.kobankat.models.StoreProduct
 import io.shortway.kobankat.models.StoreTransaction
 
+/**
+ * A listener interface responsible for handling promotional product purchases (App Store only) and
+ * changes to customer information.
+ */
 public interface PurchasesDelegate {
 
     /**

core/src/commonMain/kotlin/io/shortway/kobankat/PurchasesException.kt

@@ -1,5 +1,8 @@
 package io.shortway.kobankat
 
+/**
+ * An exception wrapping a [PurchasesError].
+ */
 public open class PurchasesException(public val error: PurchasesError) : Exception() {
 
     public val code: PurchasesErrorCode

core/src/commonMain/kotlin/io/shortway/kobankat/PurchasesFactory.kt

@@ -1,10 +1,22 @@
 package io.shortway.kobankat
 
+import io.shortway.kobankat.PurchasesFactory.sharedInstance
 import io.shortway.kobankat.models.BillingFeature
 import kotlin.jvm.JvmOverloads
 import kotlin.jvm.JvmStatic
 
+/**
+ * Factory of [Purchases]. Call `configure()` in each respective platform source set before
+ * accessing the singleton Purchases instance using [sharedInstance].
+ */
 public expect object PurchasesFactory {
+
+    /**
+     * Singleton instance of Purchases. `configure()` will set this. Will throw an exception if the
+     * shared instance has not been configured.
+     *
+     * @return A previously set singleton Purchases instance.
+     */
     public val sharedInstance: Purchases
 
     /**

core/src/commonMain/kotlin/io/shortway/kobankat/PurchasesTransactionException.kt

@@ -1,6 +1,13 @@
 package io.shortway.kobankat
 
+/**
+ * An exception indicating an error occurred during a transaction. Extends [PurchasesException] by
+ * adding a [userCancelled] property.
+ */
 public class PurchasesTransactionException(
     purchasesError: PurchasesError,
+    /**
+     * Whether the user cancelled the transaction.
+     */
     public val userCancelled: Boolean,
 ) : PurchasesException(purchasesError)

core/src/commonMain/kotlin/io/shortway/kobankat/errors.kt

@@ -18,6 +18,9 @@ public class PurchasesError(
     }
 }
 
+/**
+ * A predefined error type.
+ */
 public enum class PurchasesErrorCode(public val code: Int, public val description: String) {
     UnknownError(0, "Unknown error."),
     PurchaseCancelledError(1, "Purchase was cancelled."),

core/src/commonMain/kotlin/io/shortway/kobankat/i18n/Locale.kt

@@ -1,11 +1,24 @@
 package io.shortway.kobankat.i18n
 
-@Suppress("DataClassPrivateConstructor")
-public data class Locale private constructor(val languageCode: String, val countryCode: String) {
+/**
+ * Minimal representation of a locale.
+ */
+public class Locale private constructor(
+    public val languageCode: String,
+    public val countryCode: String
+) {
 
     public companion object {
         public val Default: Locale = defaultLocale()
 
+        /**
+         * Creates a new Locale instance.
+         *
+         * @param languageCode A 2-letter [ISO 639](https://en.wikipedia.org/wiki/ISO_639) language
+         * code.
+         * @param countryCode A 0, 2 or 3-letter
+         * [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code.
+         */
         public fun create(languageCode: String, countryCode: String): Locale =
             Locale(
                 languageCode = languageCode.lowercase(),

core/src/commonMain/kotlin/io/shortway/kobankat/models/GoogleReplacementMode.kt

@@ -2,6 +2,14 @@ package io.shortway.kobankat.models
 
 import io.shortway.kobankat.ReplacementMode
 
+/**
+ * Enum of possible replacement modes to be passed to a Play Store purchase.
+ * Ignored for Amazon and App Store purchases.
+ *
+ * See
+ * [developer.android.com](https://developer.android.com/google/play/billing/subscriptions#proration)
+ * for examples.
+ */
 public expect enum class GoogleReplacementMode: ReplacementMode {
     /**
      * Old subscription is cancelled, and new subscription takes effect immediately.

core/src/commonMain/kotlin/io/shortway/kobankat/models/Period.kt

@@ -6,7 +6,14 @@ private const val DAYS_PER_YEAR = 365.0
 private const val MONTHS_PER_YEAR = 12.0
 private const val WEEKS_PER_MONTH = DAYS_PER_YEAR / MONTHS_PER_YEAR / DAYS_PER_WEEK
 
+/**
+ * Represents subscription or [PricingPhase] billing period.
+ */
 public expect class Period
+
+/**
+ * The unit of time a [Period] is denoted in.
+ */
 public expect enum class PeriodUnit {
     DAY,
     WEEK,

core/src/commonMain/kotlin/io/shortway/kobankat/models/Price.kt

@@ -1,5 +1,8 @@
 package io.shortway.kobankat.models
 
+/**
+ * Represents a monetary price.
+ */
 public expect class Price {
     /**
      * Formatted price of the item, including its currency sign. For example $3.00.

core/src/commonMain/kotlin/io/shortway/kobankat/models/PurchasingData.kt

@@ -2,6 +2,9 @@ package io.shortway.kobankat.models
 
 import io.shortway.kobankat.ProductType
 
+/**
+ * Data connected to a purchase.
+ */
 public expect interface PurchasingData {
     public val productId: String
     public val productType: ProductType