tor-browser

commit b0d730fb2af22b556adbf05e9489f54c32f3ee12
parent 8b78933140c7e21e2f6fe7b4e74985b170e66af9
Author: t-p-white <towhite@mozilla.com>
Date:   Mon,  8 Dec 2025 19:43:24 +0000

Bug 2002784 - Update lazyFeatureFlagPreference description to add more guidance to consumers. r=android-reviewers,mavduevskiy

Differential Revision: https://phabricator.services.mozilla.com/D274294

Diffstat:
M
mobile/android/fenix/app/src/main/java/org/mozilla/fenix/components/settings/FeatureFlagPreference.kt
 | 
35
+++++++++++++++++++++++++++++++----

1 file changed, 31 insertions(+), 4 deletions(-)
diff --git a/mobile/android/fenix/app/src/main/java/org/mozilla/fenix/components/settings/FeatureFlagPreference.kt b/mobile/android/fenix/app/src/main/java/org/mozilla/fenix/components/settings/FeatureFlagPreference.kt
@@ -7,6 +7,7 @@ package org.mozilla.fenix.components.settings
 import androidx.core.content.edit
 import mozilla.components.support.ktx.android.content.PreferencesHolder
 import mozilla.components.support.ktx.android.content.booleanPreference
+import org.mozilla.fenix.FeatureFlags
 import kotlin.properties.ReadWriteProperty
 import kotlin.reflect.KProperty
 
@@ -40,11 +41,37 @@ private class LazyPreference(val key: String, val default: () -> Boolean) :
 }
 
 /**
- * Property delegate for getting and setting lazily a boolean shared preference gated by a feature flag.
+ * Property delegate for lazily getting and setting a boolean shared preference gated by a feature flag.
  *
- * @param key Key for the shared preference.
- * @param featureFlag If true, returns the shared preference value. If false, returns false.
- * @param default Default value to return.
+ * @param key The key for the shared preference.
+ * @param featureFlag If `true`, the shared preference value is returned; if `false`, this always
+ * returns `false`, regardless of the stored value.
+ *
+ * Note: If you intend to always pass `true` for [featureFlag], consider using [booleanPreference]
+ * directly instead, as the feature flag provides no additional behavior in that case.
+ *
+ * For example, this is **not** recommended:
+ * ```
+ * val isMyFeatureEnabled by lazyFeatureFlagPreference(
+ *     …
+ *     isMyFeatureEnabled = true,
+ *     …
+ * )
+ * ```
+ *
+ * [featureFlag] may be controlled through various mechanisms - for example, via an
+ * alternative feature-flag system like [FeatureFlags], or internal conditionals.
+ *
+ * For example, recommended use:
+ * ```
+ * val isMyFeatureEnabled by lazyFeatureFlagPreference(
+ *     …
+ *     isMyFeatureEnabled = FeatureFlags.onboardingFeatureEnabled,
+ *     …
+ * )
+ * ```
+ *
+ * @param default The default value to return when the preference is unset.
  */
 fun lazyFeatureFlagPreference(key: String, featureFlag: Boolean, default: () -> Boolean) =
     if (featureFlag) {