From 6bdd2ca35bb03a51f83e801d38c783d81be87dab Mon Sep 17 00:00:00 2001 From: Ryan VanderMeulen Date: Tue, 1 Oct 2024 23:10:45 -0400 Subject: [PATCH] Add and improve documentation --- .../browser/addons/AddonSettingsActivity.kt | 18 ++++++++-- .../autofill/AutofillConfirmActivity.kt | 12 +++++++ .../browser/settings/AboutFragment.kt | 7 ++++ .../settings/AccountSettingsFragment.kt | 35 +++++++++++++++++-- config/detekt-baseline.xml | 5 --- 5 files changed, 67 insertions(+), 10 deletions(-) diff --git a/app/src/main/java/org/mozilla/reference/browser/addons/AddonSettingsActivity.kt b/app/src/main/java/org/mozilla/reference/browser/addons/AddonSettingsActivity.kt index 0476e1c7d..3d8861a60 100644 --- a/app/src/main/java/org/mozilla/reference/browser/addons/AddonSettingsActivity.kt +++ b/app/src/main/java/org/mozilla/reference/browser/addons/AddonSettingsActivity.kt @@ -22,7 +22,9 @@ import org.mozilla.reference.browser.R import org.mozilla.reference.browser.ext.components /** - * An activity to show the settings of an add-on. + * [AddonSettingsActivity] is an activity that displays the settings of a specific add-on. + * It creates and hosts a [AddonSettingsFragment], passing the add-on details to the fragment + * for rendering the settings page of the add-on. */ class AddonSettingsActivity : AppCompatActivity() { @@ -49,7 +51,8 @@ class AddonSettingsActivity : AppCompatActivity() { } /** - * A fragment to show the settings of an add-on with [EngineView]. + * [AddonSettingsFragment] is a fragment responsible for displaying the settings of an add-on. + * It uses [EngineView] to load and render the add-on's settings page, specified by its `optionsPageUrl`. */ class AddonSettingsFragment : Fragment() { private lateinit var optionsPageUrl: String @@ -81,9 +84,18 @@ class AddonSettingsActivity : AppCompatActivity() { super.onDestroyView() } + /** + * Companion object for [AddonSettingsFragment]. + * + * Provides a method to create a new instance of [AddonSettingsFragment] with the required + * add-on details passed as arguments. + */ companion object { /** - * Create an [AddonSettingsFragment] with add_on as a required parameter. + * Creates a new instance of [AddonSettingsFragment] with the provided [Addon] passed as an argument. + * + * @param addon The [Addon] for which settings are being displayed. + * @return A new instance of [AddonSettingsFragment] with the add-on data passed in. */ fun create(addon: Addon) = AddonSettingsFragment().apply { arguments = Bundle().apply { diff --git a/app/src/main/java/org/mozilla/reference/browser/autofill/AutofillConfirmActivity.kt b/app/src/main/java/org/mozilla/reference/browser/autofill/AutofillConfirmActivity.kt index 537028101..a5e53c8ac 100644 --- a/app/src/main/java/org/mozilla/reference/browser/autofill/AutofillConfirmActivity.kt +++ b/app/src/main/java/org/mozilla/reference/browser/autofill/AutofillConfirmActivity.kt @@ -10,7 +10,19 @@ import mozilla.components.feature.autofill.AutofillConfiguration import mozilla.components.feature.autofill.ui.AbstractAutofillConfirmActivity import org.mozilla.reference.browser.ext.components +/** + * [AutofillConfirmActivity] is an activity that confirms autofill actions, part of + * the Android Autofill framework. It extends [AbstractAutofillConfirmActivity] and provides + * a configuration to the autofill system. + * + * This activity is only available for devices running Android O (API level 26) or above. + */ @RequiresApi(Build.VERSION_CODES.O) class AutofillConfirmActivity : AbstractAutofillConfirmActivity() { + /** + * The [AutofillConfiguration] for this activity, retrieved lazily from the + * application's components. This configuration defines how autofill should behave + * and what data it should use. + */ override val configuration: AutofillConfiguration by lazy { components.autofillConfiguration } } diff --git a/app/src/main/java/org/mozilla/reference/browser/settings/AboutFragment.kt b/app/src/main/java/org/mozilla/reference/browser/settings/AboutFragment.kt index 5b27c2f66..a40c60909 100644 --- a/app/src/main/java/org/mozilla/reference/browser/settings/AboutFragment.kt +++ b/app/src/main/java/org/mozilla/reference/browser/settings/AboutFragment.kt @@ -24,6 +24,13 @@ import org.mozilla.geckoview.BuildConfig.MOZ_APP_BUILDID import org.mozilla.geckoview.BuildConfig.MOZ_APP_VERSION import org.mozilla.reference.browser.R +/** + * [AboutFragment] is a Fragment that displays the About page of the application. + * + * This fragment inflates a layout containing details about the application, including + * the app name, version information, and additional metadata. The user can view and copy + * version information to the clipboard. + */ class AboutFragment : Fragment() { override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View? { return inflater.inflate(R.layout.fragment_about, container, false) diff --git a/app/src/main/java/org/mozilla/reference/browser/settings/AccountSettingsFragment.kt b/app/src/main/java/org/mozilla/reference/browser/settings/AccountSettingsFragment.kt index a013caf25..7ce9398cc 100644 --- a/app/src/main/java/org/mozilla/reference/browser/settings/AccountSettingsFragment.kt +++ b/app/src/main/java/org/mozilla/reference/browser/settings/AccountSettingsFragment.kt @@ -36,8 +36,20 @@ import org.mozilla.reference.browser.ext.getPreferenceKey import org.mozilla.reference.browser.ext.requireComponents import org.mozilla.reference.browser.sync.BrowserFxAEntryPoint +/** + * [AccountSettingsFragment] is a fragment that displays and manages the account settings for + * the user's Firefox Account (FxA). It handles preferences related to syncing, sign-out, and account management. + * + * The fragment provides options to manually trigger a sync, manage sync engines (like History, Passwords, Tabs), + * and shows the last time the account was synced. It also allows the user to manage their Firefox Account using a + * custom tab. + */ class AccountSettingsFragment : PreferenceFragmentCompat() { private val syncStatusObserver = object : SyncStatusObserver { + /** + * Called when the sync operation starts. Disables the "Sync Now" preference and updates its title + * to indicate that a sync is in progress. + */ override fun onStarted() { CoroutineScope(Dispatchers.Main).launch { val pref = findPreference(requireContext().getPreferenceKey(pref_key_sync_now)) @@ -47,7 +59,10 @@ class AccountSettingsFragment : PreferenceFragmentCompat() { } } - // Sync stopped successfully. + /** + * Called when the sync operation successfully completes. Re-enables the "Sync Now" preference and + * updates its title and summary to reflect the last sync time. + */ override fun onIdle() { CoroutineScope(Dispatchers.Main).launch { val pref = findPreference(requireContext().getPreferenceKey(pref_key_sync_now)) @@ -58,7 +73,10 @@ class AccountSettingsFragment : PreferenceFragmentCompat() { } } - // Sync stopped after encountering a problem. + /** + * Called when the sync operation encounters an error. Re-enables the "Sync Now" preference and updates + * its summary to reflect the sync failure. + */ override fun onError(error: Exception?) { CoroutineScope(Dispatchers.Main).launch { val pref = findPreference(requireContext().getPreferenceKey(pref_key_sync_now)) @@ -69,6 +87,12 @@ class AccountSettingsFragment : PreferenceFragmentCompat() { } } + /** + * Initializes the preferences from the XML resource and sets up listeners for the sync-related preferences. + * + * @param savedInstanceState The saved instance state of the fragment. + * @param rootKey If non-null, this preference fragment should be rooted at the preference with this key. + */ override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) { setPreferencesFromResource(R.xml.account_preferences, rootKey) @@ -111,6 +135,13 @@ class AccountSettingsFragment : PreferenceFragmentCompat() { ) } + /** + * Updates the "Last Synced" preference to show the most recent sync time or failure message. + * + * @param context The context to access resources and settings. + * @param pref The preference to update the summary for, representing the sync status. + * @param failed A boolean indicating whether the last sync attempt failed. + */ fun updateLastSyncedTimePref(context: Context, pref: Preference?, failed: Boolean = false) { val lastSyncTime = getLastSynced(context) diff --git a/config/detekt-baseline.xml b/config/detekt-baseline.xml index f6124cffd..467abb3f9 100644 --- a/config/detekt-baseline.xml +++ b/config/detekt-baseline.xml @@ -2,10 +2,6 @@ - UndocumentedPublicClass:AboutFragment.kt$AboutFragment : Fragment - UndocumentedPublicClass:AccountSettingsFragment.kt$AccountSettingsFragment : PreferenceFragmentCompat - UndocumentedPublicClass:AddonSettingsActivity.kt$AddonSettingsActivity.AddonSettingsFragment$Companion - UndocumentedPublicClass:AutofillConfirmActivity.kt$AutofillConfirmActivity : AbstractAutofillConfirmActivity UndocumentedPublicClass:AutofillPreference.kt$AutofillPreference : Preference UndocumentedPublicClass:AutofillPreference.kt$AutofillPreference$Companion UndocumentedPublicClass:AutofillSearchActivity.kt$AutofillSearchActivity : AbstractAutofillSearchActivity @@ -62,7 +58,6 @@ UndocumentedPublicClass:WebExtensionActionPopupActivity.kt$WebExtensionActionPopupActivity.WebExtensionActionPopupFragment$Companion UndocumentedPublicClass:WebExtensionPromptFeature.kt$WebExtensionPromptFeature$Companion UndocumentedPublicClass:WebPushEngineIntegration.kt$WebPushEngineIntegration : Observer - UndocumentedPublicFunction:AccountSettingsFragment.kt$AccountSettingsFragment$fun updateLastSyncedTimePref(context: Context, pref: Preference?, failed: Boolean = false) UndocumentedPublicFunction:Analytics.kt$fun isSentryEnabled() UndocumentedPublicFunction:AutofillPreference.kt$AutofillPreference$fun updateSwitch() UndocumentedPublicFunction:AutofillPreference.kt$AutofillPreference.Companion$fun isSupported(context: Context): Boolean