chore: Improve public API KDoc coverage

.changeset/public-kdocs-shine.md

@@ -0,0 +1,7 @@
+---
+"posthog": patch
+"posthog-android": patch
+"posthog-server": patch
+---
+
+Improve public API KDoc coverage.

posthog-android/src/main/java/com/posthog/android/PostHogAndroid.kt

@@ -29,19 +29,20 @@ import com.posthog.vendor.uuid.TimeBasedEpochGenerator
 import java.io.File
 
 /**
- * Main entrypoint for the Android SDK
- * Use the setup method to set a global and singleton instance
- * Or use the with method that returns an instance that you can hold and pass it around
+ * Main entry point for the Android SDK.
+ *
+ * Use [setup] to configure the process-wide singleton, or [with] to create an instance that you
+ * hold and pass around.
  */
 public class PostHogAndroid private constructor() {
     public companion object {
         private val lock = Any()
 
         /**
-         * Setup the SDK and set a global and singleton instance
-         * @param T the type of the Config
-         * @property context the Context
-         * @property config the Config
+         * Sets up the SDK and stores it as the global singleton.
+         *
+         * @param context Android context; the application context is retained internally.
+         * @param config Android SDK configuration.
          */
         public fun <T : PostHogAndroidConfig> setup(
             context: Context,
@@ -55,16 +56,15 @@ public class PostHogAndroid private constructor() {
         }
 
         /**
-         * Setup the SDK and returns an instance that you can hold and pass it around
+         * Creates and returns a configured SDK instance that you can hold and pass around.
          *
-         * All default PostHogIntegration's will only be installed for the very 1st instance,
-         * either that be created with the [setup] or [with] method otherwise they would race each other
-         * and cause issues, so the 1st instance of the SDK that is created on the hosting app
-         * will hold all installed integrations, the order of the setup matters.
+         * Default PostHog integrations are installed only on the first instance created by either
+         * [setup] or [with]. The first instance in the host app owns those integrations, so setup
+         * order matters.
          *
-         * @param T the type of the Config
-         * @property context the Context
-         * @property config the Config
+         * @param context Android context; the application context is retained internally.
+         * @param config Android SDK configuration.
+         * @return The configured PostHog client instance.
          */
         public fun <T : PostHogAndroidConfig> with(
             context: Context,

posthog-android/src/main/java/com/posthog/android/PostHogAndroidConfig.kt

@@ -8,15 +8,19 @@ import com.posthog.internal.PostHogApiEndpoint
 import com.posthog.internal.PostHogQueue
 
 /**
- * The SDK Config
- * @property apiKey the PostHog API Key
- * @property captureApplicationLifecycleEvents captures lifecycle events such as app installed, app updated, app opened and backgrounded
- * @property captureDeepLinks captures deep links events
- * @property captureScreenViews automatically captures a `$screen` event whenever a foreground
- * Activity starts (via `ActivityLifecycleCallbacks.onActivityStarted`). When enabled, the most
- * recent screen name is also attached as `$screen_name` to every subsequent event captured by
- * the SDK. To opt out of `$screen_name` stamping entirely, set to `false` AND avoid calling
- * `PostHog.screen(...)` manually. Default: `true`.
+ * Android SDK configuration.
+ *
+ * @param apiKey PostHog project API key. Leading and trailing whitespace is trimmed.
+ * @param host PostHog ingestion host. Defaults to [DEFAULT_HOST].
+ * @property captureApplicationLifecycleEvents Whether to capture application lifecycle events
+ *   automatically, including app installed, app updated, app opened, and app backgrounded.
+ * @property captureDeepLinks Whether to capture `Deep Link Opened` events automatically.
+ * @property captureScreenViews Whether to capture a `$screen` event whenever a foreground
+ *   Activity starts (via `ActivityLifecycleCallbacks.onActivityStarted`). When enabled, the most
+ *   recent screen name is also attached as `$screen_name` to every subsequent event captured by
+ *   the SDK. To opt out of `$screen_name` stamping entirely, set this to `false` and avoid calling
+ *   `PostHog.screen(...)` manually. Default: `true`.
+ * @property sessionReplayConfig Android-specific session replay capture options.
  */
 public open class PostHogAndroidConfig
     @JvmOverloads

posthog-android/src/main/java/com/posthog/android/replay/PostHogDrawableConverter.kt

@@ -3,6 +3,16 @@ package com.posthog.android.replay
 import android.graphics.Bitmap
 import android.graphics.drawable.Drawable
 
+/**
+ * Converts Android [Drawable] instances that the SDK cannot render by default into [Bitmap]s for
+ * session replay screenshots or wireframes.
+ */
 public fun interface PostHogDrawableConverter {
+    /**
+     * Converts [drawable] to a bitmap representation.
+     *
+     * @param drawable Drawable to convert.
+     * @return A bitmap to capture, or `null` when this converter cannot handle the drawable.
+     */
     public fun convert(drawable: Drawable): Bitmap?
 }

posthog-android/src/main/java/com/posthog/android/replay/PostHogMaskModifier.kt

@@ -6,16 +6,21 @@ import androidx.compose.ui.semantics.semantics
 import com.posthog.android.replay.PostHogReplayIntegration.Companion.PH_NO_CAPTURE_LABEL
 import com.posthog.android.replay.PostHogReplayIntegration.Companion.PH_NO_MASK_LABEL
 
+/**
+ * Jetpack Compose modifiers for controlling masking in Android session replay captures.
+ */
 public object PostHogMaskModifier {
     internal val PostHogReplayMask = SemanticsPropertyKey<Boolean>(PH_NO_CAPTURE_LABEL)
     internal val PostHogReplayUnmask = SemanticsPropertyKey<Boolean>(PH_NO_MASK_LABEL)
 
     /**
      * Modifier to mask elements in the session replay.
-     * @param isEnabled If true, the modifier takes effect and the element will be masked in the session replay.
-     * If false, the modifier has no effect, as if it was never applied.
-     * This is useful for controlling masking dynamically via a global setting or remote config
-     * without having to add or remove the modifier from the composable tree.
+     *
+     * @param isEnabled If true, the modifier takes effect and the element will be masked in the
+     *   session replay. If false, the modifier has no effect, as if it was never applied. This is
+     *   useful for controlling masking dynamically via a global setting or remote config without
+     *   having to add or remove the modifier from the composable tree.
+     * @return A [Modifier] with PostHog masking semantics applied.
      */
     public fun Modifier.postHogMask(isEnabled: Boolean = true): Modifier {
         return semantics(
@@ -27,12 +32,16 @@ public object PostHogMaskModifier {
 
     /**
      * Modifier to explicitly unmask elements in the session replay.
-     * When applied, the element will NOT be masked even if maskAllTextInputs or maskAllImages is enabled.
-     * This modifier takes precedence over the global masking configuration and [postHogMask].
-     * @param isEnabled If true, the modifier takes effect and the element will not be masked in the session replay.
-     * If false, the modifier has no effect, as if it was never applied.
-     * This is useful for controlling unmasking dynamically via a global setting or remote config
-     * without having to add or remove the modifier from the composable tree.
+     *
+     * When applied, the element will not be masked even if `maskAllTextInputs` or `maskAllImages`
+     * is enabled. This modifier takes precedence over the global masking configuration and
+     * [postHogMask].
+     *
+     * @param isEnabled If true, the modifier takes effect and the element will not be masked in the
+     *   session replay. If false, the modifier has no effect, as if it was never applied. This is
+     *   useful for controlling unmasking dynamically via a global setting or remote config without
+     *   having to add or remove the modifier from the composable tree.
+     * @return A [Modifier] with PostHog unmasking semantics applied.
      */
     public fun Modifier.postHogUnmask(isEnabled: Boolean = true): Modifier {
         return semantics(

posthog-android/src/main/java/com/posthog/android/replay/PostHogSessionReplayConfig.kt

@@ -1,5 +1,11 @@
 package com.posthog.android.replay
 
+/**
+ * Android session replay capture options.
+ *
+ * Use this as `PostHogAndroidConfig.sessionReplayConfig` when enabling session replay through
+ * `PostHogConfig.sessionReplay`.
+ */
 public class PostHogSessionReplayConfig
     @JvmOverloads
     constructor(
@@ -31,27 +37,26 @@ public class PostHogSessionReplayConfig
          */
         public var screenshot: Boolean = false,
         /**
-         * Deboucer delay used to reduce the number of snapshots captured and reduce performance impact
-         * This is used for capturing the view as a wireframe or screenshot
-         * The lower the number more snapshots will be captured but higher the performance impact
-         * Defaults to 1000ms = 1s
-         * Ps: it was 500ms by default until version 3.8.2
+         * Debouncer delay used to reduce the number of snapshots captured and reduce performance impact.
+         * This is used for capturing the view as a wireframe or screenshot.
+         * The lower the number, the more snapshots are captured and the higher the performance impact.
+         * Defaults to 1000ms = 1s.
+         * Ps: it was 500ms by default until version 3.8.2.
          */
         @Deprecated("Use throttleDelayMs instead")
         public var debouncerDelayMs: Long = 1000,
         /**
-         * Throttling delay used to reduce the number of snapshots captured and reduce performance impact
-         * This is used for capturing the view as a wireframe or screenshot
-         * The lower the number more snapshots will be captured but higher the performance impact
-         * Defaults to 1000ms = 1s
+         * Throttling delay used to reduce the number of snapshots captured and reduce performance impact.
+         * This is used for capturing the view as a wireframe or screenshot.
+         * The lower the number, the more snapshots are captured and the higher the performance impact.
+         * Defaults to 1000ms = 1s.
          */
         public var throttleDelayMs: Long = 1000,
         /**
          * Local sample rate for session recording, a value between 0.0 and 1.0.
          * When set, this takes precedence over the remote config sample rate.
-         * null means no local override (use the remote config value).
-         * This is a convenience property that sets PostHogConfig.sampleRate.
-         * Defaults to null
+         * `null` means no local override, so the SDK uses the remote config value.
+         * Defaults to `null`.
          */
         public var sampleRate: Double? = null,
     ) {

posthog-server/src/main/java/com/posthog/server/PostHog.kt

@@ -344,9 +344,10 @@ public class PostHog : PostHogStateless(), PostHogInterface {
 
     public companion object {
         /**
-         * Set up the SDK and returns an instance that you can hold and pass it around
-         * @param T the type of the Config
-         * @property config the Config
+         * Sets up the SDK and returns an instance that you can hold and pass around.
+         *
+         * @param config Server SDK configuration.
+         * @return The configured PostHog client instance.
          */
         @JvmStatic
         public fun <T : PostHogConfig> with(config: T): PostHogInterface {