Add and improve documentation

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 {

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 }
 }

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)

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<Preference>(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<Preference>(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<Preference>(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)
 

config/detekt-baseline.xml

@@ -2,10 +2,6 @@
 <SmellBaseline>
   <ManuallySuppressedIssues></ManuallySuppressedIssues>
   <CurrentIssues>
-    <ID>UndocumentedPublicClass:AboutFragment.kt$AboutFragment : Fragment</ID>
-    <ID>UndocumentedPublicClass:AccountSettingsFragment.kt$AccountSettingsFragment : PreferenceFragmentCompat</ID>
-    <ID>UndocumentedPublicClass:AddonSettingsActivity.kt$AddonSettingsActivity.AddonSettingsFragment$Companion</ID>
-    <ID>UndocumentedPublicClass:AutofillConfirmActivity.kt$AutofillConfirmActivity : AbstractAutofillConfirmActivity</ID>
     <ID>UndocumentedPublicClass:AutofillPreference.kt$AutofillPreference : Preference</ID>
     <ID>UndocumentedPublicClass:AutofillPreference.kt$AutofillPreference$Companion</ID>
     <ID>UndocumentedPublicClass:AutofillSearchActivity.kt$AutofillSearchActivity : AbstractAutofillSearchActivity</ID>
@@ -62,7 +58,6 @@
     <ID>UndocumentedPublicClass:WebExtensionActionPopupActivity.kt$WebExtensionActionPopupActivity.WebExtensionActionPopupFragment$Companion</ID>
     <ID>UndocumentedPublicClass:WebExtensionPromptFeature.kt$WebExtensionPromptFeature$Companion</ID>
     <ID>UndocumentedPublicClass:WebPushEngineIntegration.kt$WebPushEngineIntegration : Observer</ID>
-    <ID>UndocumentedPublicFunction:AccountSettingsFragment.kt$AccountSettingsFragment$fun updateLastSyncedTimePref(context: Context, pref: Preference?, failed: Boolean = false)</ID>
     <ID>UndocumentedPublicFunction:Analytics.kt$fun isSentryEnabled()</ID>
     <ID>UndocumentedPublicFunction:AutofillPreference.kt$AutofillPreference$fun updateSwitch()</ID>
     <ID>UndocumentedPublicFunction:AutofillPreference.kt$AutofillPreference.Companion$fun isSupported(context: Context): Boolean</ID>