Skip to content

Commit 0a04e92

Browse files
robertjamisonrobertjamison
committed
Docs: Add comprehensive KDoc to public APIs
This commit adds extensive KDoc documentation across the public API surface of the `basic-ads` library. The goal is to improve developer experience by providing clear explanations for classes, functions, and properties. * **API Documentation:** * Added detailed KDoc comments to all public classes, objects, and functions, including `BasicAds`, `AdState`, `AdSize`, `AdUnitId`, and various ad handlers (`BannerAdHandler`, `InterstitialAdHandler`, etc.). * Documented all public parameters, properties, and return values to clarify their purpose and usage. * Improved existing comments to be more descriptive and align with standard documentation practices. * **Specific Areas Updated:** * **Ad Handlers:** Clarified the lifecycle and usage of `BannerAdHandler`, `InterstitialAdHandler`, `RewardedAdHandler`, and `RewardedInterstitialAdHandler`. * **Composables:** Added documentation for `BannerAd` and `NativeAd` composables, explaining their parameters and distinguishing between loading and displaying pre-loaded ads. * **Consent Management:** Documented the `Consent`, `ConsentRequestParameters`, and `ConsentDebugSettings` classes to guide developers through the consent management flow. * **Native Ads:** Added comprehensive KDoc to `NativeAdDefault` and its component functions (`Headline`, `Body`, `Media`, etc.) on both Android and iOS. * **Core Types:** Enhanced documentation for core types like `AdSize`, `AdState`, and `AdUnitId`. Signed-off-by: Robert Jamison <65142411+robertjamison@users.noreply.github.com>
1 parent 2b881cc commit 0a04e92

23 files changed

Lines changed: 626 additions & 147 deletions

‎basic-ads/src/androidMain/kotlin/app/lexilabs/basic/ads/AdSize.kt‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,67 +2,139 @@ package app.lexilabs.basic.ads
22

33
import android.content.Context
44

5+
/**
6+
* Represents the size of an ad.
7+
*
8+
* @param width The width of the ad.
9+
* @param height The height of the ad.
10+
*/
511
public actual class AdSize public actual constructor(public actual val width: Int, public actual val height: Int) {
612

713
init {
814
com.google.android.gms.ads.AdSize(width, height)
915
}
1016

1117
public actual companion object {
18+
/** A constant for full-width ads. */
1219
public actual val FULL_WIDTH: Int = com.google.android.gms.ads.AdSize.FULL_WIDTH
20+
/** A constant for auto-height ads. */
1321
public actual val AUTO_HEIGHT: Int = com.google.android.gms.ads.AdSize.AUTO_HEIGHT
22+
/** Standard banner ad size (320x50). */
1423
public actual val BANNER: AdSize = com.google.android.gms.ads.AdSize.BANNER.toCommon()
24+
/** Full banner ad size (468x60). */
1525
public actual val FULL_BANNER: AdSize = com.google.android.gms.ads.AdSize.FULL_BANNER.toCommon()
26+
/** Large banner ad size (320x100). */
1627
public actual val LARGE_BANNER: AdSize = com.google.android.gms.ads.AdSize.LARGE_BANNER.toCommon()
28+
/** Leaderboard ad size (728x90). */
1729
public actual val LEADERBOARD: AdSize = com.google.android.gms.ads.AdSize.LEADERBOARD.toCommon()
30+
/** Medium rectangle ad size (300x250). */
1831
public actual val MEDIUM_RECTANGLE: AdSize = com.google.android.gms.ads.AdSize.MEDIUM_RECTANGLE.toCommon()
32+
/** Wide skyscraper ad size (160x600). */
1933
public actual val WIDE_SKYSCRAPER: AdSize = com.google.android.gms.ads.AdSize.WIDE_SKYSCRAPER.toCommon()
34+
/** Fluid ad size. */
2035
public actual val FLUID: AdSize = com.google.android.gms.ads.AdSize.FLUID.toCommon()
36+
/** Invalid ad size. */
2137
public actual val INVALID: AdSize = com.google.android.gms.ads.AdSize.INVALID.toCommon()
2238

39+
/**
40+
* Selects the appropriate ad size for the current platform.
41+
*
42+
* @param androidAdSize The ad size for Android.
43+
* @param iosAdSize The ad size for iOS.
44+
* @return The selected ad size.
45+
*/
2346
public actual fun autoSelect(androidAdSize: AdSize, iosAdSize: AdSize): AdSize = androidAdSize
2447

48+
/**
49+
* Gets the anchored adaptive banner ad size for the current orientation.
50+
*
51+
* @param context The context.
52+
* @param width The width of the ad.
53+
* @return The anchored adaptive banner ad size.
54+
*/
2555
public actual fun getCurrentOrientationAnchoredAdaptiveBannerAdSize(context: Any?, width: Int): AdSize {
2656
require(context != null && context is Context) {
2757
"`getCurrentOrientationAnchoredAdaptiveBannerAdSize` requires argument `context` to be an Android `Context` type"
2858
}
2959
return com.google.android.gms.ads.AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(context, width).toCommon()
3060
}
3161

62+
/**
63+
* Gets the portrait anchored adaptive banner ad size.
64+
*
65+
* @param context The context.
66+
* @param width The width of the ad.
67+
* @return The portrait anchored adaptive banner ad size.
68+
*/
3269
public actual fun getPortraitAnchoredAdaptiveBannerAdSize(context: Any?, width: Int): AdSize {
3370
require(context != null && context is Context) {
3471
"`getPortraitAnchoredAdaptiveBannerAdSize` requires argument `context` to be an Android `Context` type"
3572
}
3673
return com.google.android.gms.ads.AdSize.getPortraitAnchoredAdaptiveBannerAdSize(context, width).toCommon()
3774
}
75+
/**
76+
* Gets the landscape anchored adaptive banner ad size.
77+
*
78+
* @param context The context.
79+
* @param width The width of the ad.
80+
* @return The landscape anchored adaptive banner ad size.
81+
*/
3882
public actual fun getLandscapeAnchoredAdaptiveBannerAdSize(context: Any?, width: Int): AdSize {
3983
require(context != null && context is Context) {
4084
"`getLandscapeAnchoredAdaptiveBannerAdSize` requires argument `context` to be an Android `Context` type"
4185
}
4286
return com.google.android.gms.ads.AdSize.getLandscapeAnchoredAdaptiveBannerAdSize(context, width).toCommon()
4387
}
4488

89+
/**
90+
* Gets the inline adaptive banner ad size for the current orientation.
91+
*
92+
* @param context The context.
93+
* @param width The width of the ad.
94+
* @return The inline adaptive banner ad size.
95+
*/
4596
public actual fun getCurrentOrientationInlineAdaptiveBannerAdSize(context: Any?, width: Int): AdSize {
4697
require(context != null && context is Context) {
4798
"`getCurrentOrientationInlineAdaptiveBannerAdSize` requires argument `context` to be an Android `Context` type"
4899
}
49100
return com.google.android.gms.ads.AdSize.getCurrentOrientationInlineAdaptiveBannerAdSize(context, width).toCommon()
50101
}
51102

103+
/**
104+
* Gets the portrait inline adaptive banner ad size.
105+
*
106+
* @param context The context.
107+
* @param width The width of the ad.
108+
* @return The portrait inline adaptive banner ad size.
109+
*/
52110
public actual fun getPortraitInlineAdaptiveBannerAdSize(context: Any?, width: Int): AdSize {
53111
require(context != null && context is Context) {
54112
"`getPortraitInlineAdaptiveBannerAdSize` requires argument `context` to be an Android `Context` type"
55113
}
56114
return com.google.android.gms.ads.AdSize.getPortraitInlineAdaptiveBannerAdSize(context, width).toCommon()
57115
}
58116

117+
/**
118+
* Gets the landscape inline adaptive banner ad size.
119+
*
120+
* @param context The context.
121+
* @param width The width of the ad.
122+
* @return The landscape inline adaptive banner ad size.
123+
*/
59124
public actual fun getLandscapeInlineAdaptiveBannerAdSize(context: Any?, width: Int): AdSize {
60125
require(context != null && context is Context) {
61126
"`getLandscapeInlineAdaptiveBannerAdSize` requires argument `context` to be an Android `Context` type"
62127
}
63128
return com.google.android.gms.ads.AdSize.getLandscapeInlineAdaptiveBannerAdSize(context, width).toCommon()
64129
}
65130

131+
/**
132+
* Gets the inline adaptive banner ad size.
133+
*
134+
* @param width The width of the ad.
135+
* @param maxHeight The maximum height of the ad.
136+
* @return The inline adaptive banner ad size.
137+
*/
66138
public actual fun getInlineAdaptiveBannerAdSize(width: Int, maxHeight: Int): AdSize =
67139
com.google.android.gms.ads.AdSize.getInlineAdaptiveBannerAdSize(width, maxHeight).toCommon()
68140
}

‎basic-ads/src/androidMain/kotlin/app/lexilabs/basic/ads/AdUnitId.kt‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,28 @@
11
package app.lexilabs.basic.ads
22

3+
/**
4+
* A utility object for providing ad unit IDs.
5+
*/
36
public actual object AdUnitId {
7+
/**
8+
* Selects the appropriate ad unit ID for the current platform.
9+
* On Android, it returns the `androidAdUnitId`.
10+
*
11+
* @param androidAdUnitId The ad unit ID for Android.
12+
* @param iosAdUnitId The ad unit ID for iOS.
13+
* @return The selected ad unit ID.
14+
*/
415
public actual fun autoSelect(androidAdUnitId: String?, iosAdUnitId: String?): String {
516
return androidAdUnitId ?: ""
617
}
18+
/** The default ad unit ID for banner ads. */
719
public actual const val BANNER_DEFAULT: String = "ca-app-pub-3940256099942544/9214589741"
20+
/** The default ad unit ID for interstitial ads. */
821
public actual const val INTERSTITIAL_DEFAULT: String = "ca-app-pub-3940256099942544/1033173712"
22+
/** The default ad unit ID for rewarded interstitial ads. */
923
public actual const val REWARDED_INTERSTITIAL_DEFAULT: String = "ca-app-pub-3940256099942544/5354046379"
24+
/** The default ad unit ID for rewarded ads. */
1025
public actual const val REWARDED_DEFAULT: String = "ca-app-pub-3940256099942544/5224354917"
26+
/** The default ad unit ID for native ads. */
1127
public actual const val NATIVE_DEFAULT: String = "ca-app-pub-3940256099942544/2247696110"
1228
}

‎basic-ads/src/androidMain/kotlin/app/lexilabs/basic/ads/BannerAdHandler.kt‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,23 +10,32 @@ import app.lexilabs.basic.logging.Log
1010
import com.google.android.gms.ads.AdRequest
1111
import com.google.android.gms.ads.AdView
1212

13+
/**
14+
* A typealias for [AdView] on Android.
15+
*/
1316
public typealias BannerView = AdView
1417

18+
/**
19+
* A handler for banner ads on Android.
20+
*
21+
* @param activity The activity context.
22+
*/
1523
public actual class BannerAdHandler actual constructor(activity: Any?) {
1624

1725
private val tag = "BannerAd"
1826
private val context: Context
27+
/** The underlying [BannerView] instance. */
1928
public var bannerView: BannerView? = null
2029
private val _state: MutableState<AdState> = mutableStateOf(AdState.NONE)
2130
private val _adSize: MutableState<AdSize> = mutableStateOf(AdSize.FULL_BANNER)
2231

2332
/**
24-
* Determines the [AdState] of the [BannerAdHandler]
33+
* Determines the [AdState] of the [BannerAdHandler].
2534
*/
2635
public actual val state: AdState by _state
2736

2837
/**
29-
* Holds the active [AdSize] of the [BannerAdHandler]
38+
* Holds the active [AdSize] of the [BannerAdHandler].
3039
*/
3140
public actual val adSize: AdSize by _adSize
3241

@@ -42,6 +51,18 @@ public actual class BannerAdHandler actual constructor(activity: Any?) {
4251
context = activity
4352
}
4453

54+
/**
55+
* Loads a banner ad.
56+
*
57+
* @param adUnitId The ad unit ID.
58+
* @param adSize The size of the ad.
59+
* @param onLoad A callback invoked when the ad is loaded.
60+
* @param onFailure A callback invoked when the ad fails to load.
61+
* @param onDismissed A callback invoked when the ad is dismissed.
62+
* @param onShown A callback invoked when the ad is shown.
63+
* @param onImpression A callback invoked when an impression is recorded for the ad.
64+
* @param onClick A callback invoked when the ad is clicked.
65+
*/
4566
@RequiresPermission("android.permission.INTERNET")
4667
public actual fun load(
4768
adUnitId: String,

‎basic-ads/src/androidMain/kotlin/app/lexilabs/basic/ads/BannerAdListener.kt‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,16 @@ import app.lexilabs.basic.logging.Log
44
import com.google.android.gms.ads.AdListener
55
import com.google.android.gms.ads.LoadAdError
66

7+
/**
8+
* An [AdListener] for banner ads.
9+
*
10+
* @param onLoad A callback invoked when the ad is loaded.
11+
* @param onFailure A callback invoked when the ad fails to load.
12+
* @param onDismissed A callback invoked when the ad is dismissed.
13+
* @param onShown A callback invoked when the ad is shown.
14+
* @param onImpression A callback invoked when an impression is recorded for the ad.
15+
* @param onClick A callback invoked when the ad is clicked.
16+
*/
717
public class BannerAdListener(
818
public val onLoad: () -> Unit,
919
public val onFailure: (Exception) -> Unit,

‎basic-ads/src/androidMain/kotlin/app/lexilabs/basic/ads/BasicAds.kt‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,20 +7,32 @@ import kotlinx.coroutines.CoroutineScope
77
import kotlinx.coroutines.Dispatchers
88
import kotlinx.coroutines.launch
99

10+
/**
11+
* A utility object for initializing the Mobile Ads SDK.
12+
*/
1013
public actual object BasicAds {
1114

15+
/** The error domain for the Mobile Ads SDK. */
1216
public actual val errorDomain: String? = com.google.android.gms.ads.MobileAds.ERROR_DOMAIN
1317

18+
/** The request configuration for the Mobile Ads SDK. */
1419
@DependsOnGoogleMobileAds
1520
public actual var configuration: RequestConfiguration
1621
get() = com.google.android.gms.ads.MobileAds.getRequestConfiguration().toCommon()
1722
set(config) = com.google.android.gms.ads.MobileAds.setRequestConfiguration(config.toAndroid())
1823

24+
/** The version of the Mobile Ads SDK. */
1925
public actual val version: String = com.google.android.gms.ads.MobileAds.getVersion().toString()
2026

27+
/** Whether the Mobile Ads SDK has been initialized. */
2128
public actual val initialized: Boolean
2229
get() = com.google.android.gms.ads.MobileAds.getInitializationStatus()?.adapterStatusMap?.isNotEmpty() ?: false
2330

31+
/**
32+
* Initializes the Mobile Ads SDK.
33+
*
34+
* @param context The context to use for initialization. Must be an `Activity` on Android.
35+
*/
2436
@MainThread
2537
@RequiresPermission("android.permission.INTERNET")
2638
public actual fun initialize(context: Any?) {
@@ -32,24 +44,45 @@ public actual object BasicAds {
3244
}
3345
}
3446

47+
/**
48+
* Disables the initialization of mediation adapters.
49+
*
50+
* @param context The context to use. Must be an `Activity` on Android.
51+
*/
3552
public actual fun disableMediationAdapterInitialization(context: Any?) {
3653
require(context != null) {
3754
"Context must be set to non-null value in Android"
3855
}
3956
com.google.android.gms.ads.MobileAds.disableMediationAdapterInitialization(context as Activity)
4057
}
4158

59+
/**
60+
* Opens the ad inspector.
61+
*
62+
* @param context The context to use. Must be an `Activity` on Android.
63+
* @param adUnitId The ad unit ID to use.
64+
*/
4265
public actual fun openDebugMenu(context: Any?, adUnitId: String) {
4366
require(context != null) {
4467
"Context must be set to non-null value in Android"
4568
}
4669
com.google.android.gms.ads.MobileAds.openDebugMenu(context as Activity, adUnitId)
4770
}
4871

72+
/**
73+
* Sets whether the app's audio is muted.
74+
*
75+
* @param muted Whether to mute the app's audio.
76+
*/
4977
public actual fun setAppMuted(muted: Boolean) {
5078
com.google.android.gms.ads.MobileAds.setAppMuted(muted)
5179
}
5280

81+
/**
82+
* Sets the app's volume.
83+
*
84+
* @param volume The volume to set, from 0.0 to 1.0.
85+
*/
5386
public actual fun setAppVolume(volume: Float) {
5487
com.google.android.gms.ads.MobileAds.setAppVolume(volume)
5588
}

‎basic-ads/src/androidMain/kotlin/app/lexilabs/basic/ads/Consent.kt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,11 @@ public actual class Consent actual constructor (activity: Any?) {
2525
private val consentInformation: AndroidConsentInformation
2626

2727
private val _canRequestAds: MutableState<Boolean> = mutableStateOf(false)
28+
/** Indicates whether ads can be requested. */
2829
public actual val canRequestAds: Boolean by _canRequestAds
2930

3031
private val _privacyOptionsRequired: MutableState<Boolean> = mutableStateOf(false)
32+
/** Indicates whether a privacy options entry point is required. */
3133
public actual val privacyOptionsRequired: Boolean by _privacyOptionsRequired
3234

3335
init {
@@ -78,6 +80,7 @@ public actual class Consent actual constructor (activity: Any?) {
7880
* __Whether a privacy options entry point is required.__
7981
* Some privacy messages require apps to allow users to modify their
8082
* privacy options at any time.
83+
* @param params The consent request parameters.
8184
* @param onError lambda which passes a [ConsentException] on failure
8285
*/
8386
public actual fun requestConsentInfoUpdate(params: ConsentRequestParameters, onError: (Exception) -> Unit) {
@@ -128,6 +131,7 @@ public actual class Consent actual constructor (activity: Any?) {
128131
*
129132
* If a privacy entry point is not required, configure your UI element
130133
* to be not visible and interactable.
134+
* @return `true` if a privacy options entry point is required, `false` otherwise.
131135
*/
132136
public actual fun isPrivacyOptionsRequired(): Boolean {
133137
_privacyOptionsRequired.value = consentInformation.privacyOptionsRequirementStatus ==
@@ -157,6 +161,7 @@ public actual class Consent actual constructor (activity: Any?) {
157161
*
158162
* Before requesting ads, use [Consent.canRequestAds] to
159163
* check if you've obtained consent from the user.
164+
* @return `true` if ads can be requested, `false` otherwise.
160165
*/
161166
public actual fun canRequestAds(): Boolean {
162167
_canRequestAds.value = consentInformation.canRequestAds()

0 commit comments

Comments
 (0)