commit 90439dd151ee9e448a1950edb3a0fb118acc0a3f parent 3166cb355e99d04203aa8009403b2766d6333459 Author: mcarare <48995920+mcarare@users.noreply.github.com> Date: Tue, 7 Oct 2025 06:44:21 +0000 Bug 1992735 - Add KDoc for language related code. r=android-reviewers,avirvara This patch introduces KDoc documentation for several classes and methods related to the language selection feature to improve code clarity and maintainability. Differential Revision: https://phabricator.services.mozilla.com/D267627 Diffstat:
4 files changed, 53 insertions(+), 8 deletions(-)
diff --git a/mobile/android/focus-android/app/src/main/java/org/mozilla/focus/locale/screen/DefaultLanguageScreenInteractor.kt b/mobile/android/focus-android/app/src/main/java/org/mozilla/focus/locale/screen/DefaultLanguageScreenInteractor.kt @@ -4,10 +4,24 @@ package org.mozilla.focus.locale.screen +/** + * The default implementation of the interactor for the language selection screen. + * This class is responsible for handling user interactions and communicating them to the store. + * + * @param languageScreenStore The store responsible for managing the state of the language screen. + */ class DefaultLanguageScreenInteractor( private val languageScreenStore: LanguageScreenStore, ) { + /** + * Handles the selection of a language from the list. + * + * If the selected language is the same as the one already selected, it does nothing. + * Otherwise, it dispatches an action to the store to update the selected language. + * + * @param language The [Language] object that was selected by the user. + */ fun handleLanguageSelected(language: Language) { if (languageScreenStore.state.selectedLanguage == language) { return diff --git a/mobile/android/focus-android/app/src/main/java/org/mozilla/focus/locale/screen/LanguageScreenStore.kt b/mobile/android/focus-android/app/src/main/java/org/mozilla/focus/locale/screen/LanguageScreenStore.kt @@ -9,6 +9,21 @@ import mozilla.components.lib.state.Middleware import mozilla.components.lib.state.State import mozilla.components.lib.state.Store +/** + * A store for managing the state of the language selection screen. + * + * This store is responsible for handling the state ([LanguageScreenState]) and actions + * ([LanguageScreenAction]) related to the language selection UI. It manages the list + * of available languages and the currently selected language. + * + * On initialization, it automatically dispatches [LanguageScreenAction.InitLanguages]. This + * action is intended to be intercepted by a [Middleware] to trigger the loading of language + * data from a repository. + * + * @param initialState The initial state for the language screen. + * @param middlewares A list of [Middleware]s to intercept actions and perform side effects, + * such as fetching the language list. + */ class LanguageScreenStore( initialState: LanguageScreenState, middlewares: List<Middleware<LanguageScreenState, LanguageScreenAction>> = emptyList(), @@ -37,8 +52,25 @@ data class LanguageScreenState( * Action to dispatch through the `LanguageScreenStore` to modify `LanguageScreenState` through the reducer. */ sealed class LanguageScreenAction : Action { + /** + * An action that signals the store to initialize the list of available languages. + */ object InitLanguages : LanguageScreenAction() + + /** + * An action that represents the user selecting a new language from the list. + * + * @property selectedLanguage The language that the user has selected. + */ data class Select(val selectedLanguage: Language) : LanguageScreenAction() + + /** + * An action to update the entire list of available languages and the currently + * selected language. + * + * @property languageList The new, complete list of available languages. + * @property selectedLanguage The language that should be marked as currently selected. + */ data class UpdateLanguages( val languageList: List<Language>, val selectedLanguage: Language, diff --git a/mobile/android/focus-android/app/src/main/java/org/mozilla/focus/locale/screen/LanguageStorage.kt b/mobile/android/focus-android/app/src/main/java/org/mozilla/focus/locale/screen/LanguageStorage.kt @@ -11,6 +11,13 @@ import androidx.preference.PreferenceManager import org.mozilla.focus.R import org.mozilla.focus.generated.LocalesList +/** + * A storage class responsible for managing the application's language settings. + * It provides access to the list of available languages, the currently selected language, + * and methods for persisting the user's language choice in SharedPreferences. + * + * @param context The application context, used to access resources and SharedPreferences. + */ class LanguageStorage(private val context: Context) { private val sharedPref: SharedPreferences = PreferenceManager.getDefaultSharedPreferences(context) diff --git a/mobile/android/focus-android/quality/detekt-baseline.xml b/mobile/android/focus-android/quality/detekt-baseline.xml @@ -32,7 +32,6 @@ <ID>UndocumentedPublicClass:CustomTabsService.kt$CustomTabsService : AbstractCustomTabsService</ID> <ID>UndocumentedPublicClass:DebugFocusApplication.kt$DebugFocusApplication : FocusApplication</ID> <ID>UndocumentedPublicClass:DefaultBrowserPreference.kt$DefaultBrowserPreference : Preference</ID> - <ID>UndocumentedPublicClass:DefaultLanguageScreenInteractor.kt$DefaultLanguageScreenInteractor</ID> <ID>UndocumentedPublicClass:DefaultSitePermissionOptionsScreenInteractor.kt$DefaultSitePermissionOptionsScreenInteractor</ID> <ID>UndocumentedPublicClass:DownloadService.kt$DownloadService : AbstractFetchDownloadService</ID> <ID>UndocumentedPublicClass:EngineSharedPreferencesListener.kt$EngineSharedPreferencesListener$ChangeSource</ID> @@ -59,11 +58,6 @@ <ID>UndocumentedPublicClass:IntentProcessor.kt$IntentProcessor.Result$CustomTab : Result</ID> <ID>UndocumentedPublicClass:IntentProcessor.kt$IntentProcessor.Result$None : Result</ID> <ID>UndocumentedPublicClass:IntentProcessor.kt$IntentProcessor.Result$Tab : Result</ID> - <ID>UndocumentedPublicClass:LanguageScreenStore.kt$LanguageScreenAction$InitLanguages : LanguageScreenAction</ID> - <ID>UndocumentedPublicClass:LanguageScreenStore.kt$LanguageScreenAction$Select : LanguageScreenAction</ID> - <ID>UndocumentedPublicClass:LanguageScreenStore.kt$LanguageScreenAction$UpdateLanguages : LanguageScreenAction</ID> - <ID>UndocumentedPublicClass:LanguageScreenStore.kt$LanguageScreenStore : Store</ID> - <ID>UndocumentedPublicClass:LanguageStorage.kt$LanguageStorage</ID> <ID>UndocumentedPublicClass:LocaleDescriptor.kt$LocaleDescriptor : Comparable</ID> <ID>UndocumentedPublicClass:MainActivity.kt$MainActivity$AppOpenType</ID> <ID>UndocumentedPublicClass:ManualAddSearchEnginePreference.kt$ManualAddSearchEnginePreference : Preference</ID> @@ -151,7 +145,6 @@ <ID>UndocumentedPublicFunction:ClientWrapper.kt$ClientWrapper$@Deprecated("Non-private Client usage should be prevented") fun unwrap(): Client</ID> <ID>UndocumentedPublicFunction:CookiesPreference.kt$CookiesPreference$fun updateSummary()</ID> <ID>UndocumentedPublicFunction:DefaultBrowserPreference.kt$DefaultBrowserPreference$fun update()</ID> - <ID>UndocumentedPublicFunction:DefaultLanguageScreenInteractor.kt$DefaultLanguageScreenInteractor$fun handleLanguageSelected(language: Language)</ID> <ID>UndocumentedPublicFunction:DefaultSitePermissionOptionsScreenInteractor.kt$DefaultSitePermissionOptionsScreenInteractor$fun handleSitePermissionOptionSelected(sitePermissionOption: SitePermissionOption)</ID> <ID>UndocumentedPublicFunction:ExceptionsListFragment.kt$ExceptionsListFragment.DomainListAdapter$fun move(from: Int, to: Int)</ID> <ID>UndocumentedPublicFunction:ExceptionsListFragment.kt$ExceptionsListFragment.DomainListAdapter$fun refresh(context: Context, body: (() -> Unit)? = null)</ID> @@ -168,7 +161,6 @@ <ID>UndocumentedPublicFunction:HomeMenu.kt$HomeMenu$fun getMenuBuilder(): BrowserMenuBuilder</ID> <ID>UndocumentedPublicFunction:LocaleDescriptor.kt$LocaleDescriptor$fun getNativeName(): String?</ID> <ID>UndocumentedPublicFunction:LocaleDescriptor.kt$LocaleDescriptor$fun getTag(): String</ID> - <ID>UndocumentedPublicFunction:LocaleFragmentCompose.kt$@Composable fun LanguageNameAndTagItem( language: Language, isSelected: Boolean, onClick: (String) -> Unit, )</ID> <ID>UndocumentedPublicFunction:MainActivity.kt$MainActivity$fun getToolbar(): ActionBar</ID> <ID>UndocumentedPublicFunction:MainActivityNavigation.kt$MainActivityNavigation$@Suppress("CyclomaticComplexMethod") fun settings(page: Screen.Settings.Page)</ID> <ID>UndocumentedPublicFunction:MainActivityNavigation.kt$MainActivityNavigation$fun showOnBoardingSecondScreen()</ID>