scribe-org · andrewtavis · May 9, 2025 · Apr 24, 2025 · Apr 25, 2025 · May 6, 2025
diff --git a/app/src/main/java/be/scri/activities/MainActivity.kt b/app/src/main/java/be/scri/activities/MainActivity.kt
@@ -26,9 +26,17 @@ import be.scri.services.EnglishKeyboardIME
 import be.scri.ui.common.bottombar.bottomBarScreens
 import be.scri.ui.theme.ScribeTheme
 
+/**
+ * The main entry point of the app.
+ * Initializes theme settings, navigation, and sets up the main UI using Jetpack Compose.
+ */
 class MainActivity : ComponentActivity() {
     private var englishKeyboardIME: EnglishKeyboardIME? = null
 
+    /**
+     * Initializes the app on launch. Sets the theme based on user preferences, sets up edge-to-edge
+     * layout, and builds the UI using Compose.
+     */
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         AppCompatDelegate.setDefaultNightMode(PreferencesHelper.getUserDarkModePreference(this))
@@ -56,6 +64,12 @@ class MainActivity : ComponentActivity() {
 
             val isHintChangedMap = remember { mutableStateMapOf<Int, Boolean>() }
 
+            /**
+             * Updates the app's dark/light theme based on user preference and applies it
+             * immediately.
+             *
+             * @param darkMode Whether the dark mode should be enabled.
+             */
             fun updateTheme(darkMode: Boolean) {
                 setLightDarkModePreference(context, darkMode)
 

diff --git a/app/src/main/java/be/scri/ui/common/appcomponents/ActionBar.kt b/app/src/main/java/be/scri/ui/common/appcomponents/ActionBar.kt
@@ -18,6 +18,14 @@ import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
 import be.scri.R
 
+/**
+ * A reusable action bar component that displays a back button icon
+ * and a title text in a horizontal row.
+ *
+ * @param title The title displayed next to the back button.
+ * @param onClickAction Lambda function triggered when the back button is clicked.
+ * @param modifier Optional [Modifier] for styling and layout customization.
+ */
 @Composable
 fun ActionBar(
     title: String,

diff --git a/app/src/main/java/be/scri/ui/common/appcomponents/HintDialog.kt b/app/src/main/java/be/scri/ui/common/appcomponents/HintDialog.kt
@@ -42,6 +42,18 @@ import androidx.compose.ui.unit.sp
 import be.scri.R
 import be.scri.helpers.PreferencesHelper.getIsDarkModeOrNot
 
+/**
+ * A dialog component that displays a hint message when the specified page is visible
+ * and the hint has not been shown before or when the hint has been changed.
+ *
+ * @param pagerState The state of the pager used for controlling page navigation.
+ * @param currentPageIndex The index of the current page to determine when the hint should be shown.
+ * @param sharedPrefsKey The key used to store the hint's visibility status in shared preferences.
+ * @param hintMessageResId The resource ID of the hint message to be displayed in the dialog.
+ * @param isHintChanged A boolean flag indicating whether the hint has been updated and should be shown again.
+ * @param onDismiss A lambda function that is triggered when the dialog is dismissed, passing the current page index.
+ * @param modifier An optional [Modifier] for customizing the UI layout and styling.
+ */
 @Composable
 fun HintDialog(
     pagerState: PagerState,
@@ -88,6 +100,17 @@ fun HintDialog(
     }
 }
 
+/**
+ * A composable function that creates the content of a hint dialog.
+ * It displays a hint message, an icon, and a dismiss button.
+ * The button and icon change based on whether the user is in dark or light mode.
+ * The content is styled with a gradient background and a shadow effect.
+ *
+ * @param text The hint that will be displayed in the dialog content.
+ * @param onDismiss A callback function that is triggered when the "OK" button is clicked, dismissing the dialog.
+ * @param isUserDarkMode A boolean value indicating whether the app is in dark mode.
+ * @param modifier An optional [Modifier] used to customize the layout and styling.
+ */
 @Suppress("MagicNumber")
 @Composable
 fun HintDialogContent(

diff --git a/app/src/main/java/be/scri/ui/common/appcomponents/PageTitle.kt b/app/src/main/java/be/scri/ui/common/appcomponents/PageTitle.kt
@@ -10,6 +10,12 @@ import androidx.compose.ui.text.TextStyle
 import androidx.compose.ui.text.font.FontWeight
 import be.scri.ui.theme.ScribeTypography
 
+/**
+ * A composable function that displays a styled page title.
+ *
+ * @param pageTitle The title text to display
+ * @param modifier An optional [Modifier] used to customize the layout and styling.
+ */
 @Composable
 fun PageTitle(
     pageTitle: String,

diff --git a/app/src/main/java/be/scri/ui/common/bottombar/BottomBarScreen.kt b/app/src/main/java/be/scri/ui/common/bottombar/BottomBarScreen.kt
@@ -14,18 +14,27 @@ sealed class BottomBarScreen(
     @DrawableRes val icon: Int,
     val label: String,
 ) {
+    /**
+     * Represents the Installation screen and its associated route.
+     */
     data object Installation : BottomBarScreen(
         Screen.Installation.route,
         R.drawable.material_keyboard,
         "Installation",
     )
 
+    /**
+     * Represents the Settings screen and its associated route.
+     */
     data object Settings : BottomBarScreen(
            Screen.Settings.route,
         R.drawable.material_settings,
         "Settings",
     )
 
+    /**
+     * Represents the About screen and its associated route.
+     */
     data object About : BottomBarScreen(
         Screen.About.route,
         R.drawable.material_info,

diff --git a/app/src/main/java/be/scri/ui/models/ScribeItem.kt b/app/src/main/java/be/scri/ui/models/ScribeItem.kt
@@ -4,26 +4,60 @@ package be.scri.ui.models
 
 import androidx.annotation.DrawableRes
 
-/**
- * A class defining different types of items used in the application interface.
- */
+/** A class defining different types of items used in the application inter
9E81
face. */
 sealed class ScribeItem(
     open val title: Int,
     open val desc: Int?,
 ) {
+    /**
+     * Represents a clickable item in the Scribe UI, typically used for actions like navigation or
+     * triggering events.
+     *
+     * Inherits from [ScribeItem] and adds a lambda [action] that defines what happens when the item
+     * is clicked.
+     *
+     * @property title The string resource ID for the item's title.
+     * @property desc (Optional) The string resource ID for the item's description.
+     * @property action The callback function to invoke when the item is clicked.
+     */
     data class ClickableItem(
         override val title: Int,
         override val desc: Int? = null,
         val action: () -> Unit,
     ) : ScribeItem(title, desc)
 
+    /**
+     * Represents a toggleable switch item in the Scribe UI.
+     *
+     * Inherits from [ScribeItem] and adds a [state] to represent the current switch value, and a
+     * [onToggle] lambda to handle state changes when toggled.
+     *
+     * @property title The string resource ID for the item's title.
+     * @property desc The string resource ID for the item's description.
+     * @property state The current state of the switch (true for on, false for off).
+     * @property onToggle The callback function invoked with the new state when the switch is
+     * toggled.
+     */
     data class SwitchItem(
         override val title: Int,
         override val desc: Int,
         val state: Boolean,
         val onToggle: (Boolean) -> Unit,
     ) : ScribeItem(title, desc)
 
+    /**
+     * Represents an external link item in the Scribe UI.
+     *
+     * Inherits from [ScribeItem] and adds support for leading and trailing icons, an external URL,
+     * and a click handler.
+     *
+     * @property title The string resource ID for the item's title.
+     * @property desc (Optional) The string resource ID for the item's description.
+     * @property leadingIcon The drawable resource ID for the icon displayed before the title.
+     * @property trailingIcon The drawable resource ID for the icon displayed after the title.
+     * @property url The external URL to open when the item is clicked.
+     * @property onClick The callback function invoked when the item is clicked.
+     */
     data class ExternalLinkItem(
         override val title: Int,
         override val desc: Int? = null,
@@ -33,6 +67,15 @@ sealed class ScribeItem(
         val onClick: () -> Unit,
     ) : ScribeItem(title, desc)
 
+    /**
+     * Represents a custom item in the Scribe UI.
+     *
+     * Inherits from [ScribeItem] and adds support for executing a custom action.
+     *
+     * @property title The string resource ID for the item's title.
+     * @property desc (Optional) The string resource ID for the item's description.
+     * @property customAction The callback function to execute when the item is triggered.
+     */
     data class CustomItem(
         override val title: Int,
         override val desc: Int,

diff --git a/app/src/main/java/be/scri/ui/screens/InstallationScreen.kt b/app/src/main/java/be/scri/ui/screens/InstallationScreen.kt
@@ -310,6 +310,10 @@ fun InstallationScreen(
     }
 }
 
+/**
+ * Defines commonly used dimensions for the Installation screen UI.
+ * Includes padding, text sizes, icon size, and elevation values.
+ */
 object Dimensions {
     val PaddingSmall = 8.dp
     val PaddingMedium = 16.dp
@@ -330,6 +334,9 @@ object Dimensions {
     const val LEFT_LAYOUT_DIRECTION = 0f
 }
 
+/**
+ * Defines commonly used alpha (transparency) values for UI elements.
+ */
 object Alpha {
     const val HIGH = 0.9f
     const val MEDIUM = 0.6f

diff --git a/app/src/main/java/be/scri/ui/screens/LanguageSettingsScreen.kt b/app/src/main/java/be/scri/ui/screens/LanguageSettingsScreen.kt
@@ -224,6 +224,26 @@ fun LanguageSettingsScreen(
     }
 }
 
+/**
+ * Builds a list of toggleable functionality settings for the keyboard.
+ *
+ * These settings include:
+ * - Double-space for period
+ * - Emoji suggestions
+ * - Keypress vibration
+ * - Popup on keypress
+ *
+ * @param periodOnDoubleTapState Current state of the double-space period setting.
+ * @param onTogglePeriodOnDoubleTap Callback invoked when the double-space period is toggled.
+ * @param emojiSuggestionsState Current state of the emoji suggestions setting.
+ * @param onToggleEmojiSuggestions Callback invoked when emoji suggestions is t
10000
oggled.
+ * @param togglePopUpOnKeyPress Current state of popup on keypress setting.
+ * @param onTogglePopUpOnKeyPress Callback invoked when popup on keypress is toggled.
+ * @param toggleVibrateOnKeyPress Current state of keypress vibration setting.
+ * @param onToggleVibrateOnKeyPress Callback invoked when keypress vibration is toggled.
+ *
+ * @return A list of [ScribeItem]s to be shown in the UI.
+ */
 @Composable
 private fun getFunctionalityListData(
     periodOnDoubleTapState: Boolean,
@@ -265,6 +285,21 @@ private fun getFunctionalityListData(
     return list
 }
 
+/**
+ * Returns a list of [ScribeItem]s representing layout-specific settings based on the selected [language].
+ *
+ * Includes toggles such as:
+ * - "Disable accent characters" (conditionally shown for German, Swedish, and Spanish)
+ * - "Period and comma" toggle (always included)
+ *
+ * @param language The currently selected language, used to determine which layout-specific settings to show.
+ * @param togglePeriodAndCommaState Current state of the "Period and comma" toggle.
+ * @param onTogglePeriodAndComma Callback invoked when the "Period and comma" toggle is changed.
+ * @param toggleDisableAccentCharacter Current state of the "Disable accent characters" toggle.
+ * @param onToggleDisableAccentCharacter Callback invoked when the "Disable accent characters" toggle is changed.
+ *
+ * @return A list of [ScribeItem]s to be displayed in the UI.
+ */
 @Composable
 private fun getLayoutListData(
     language: String,
@@ -300,6 +335,14 @@ private fun getLayoutListData(
     return list
 }
 
+/**
+ * Returns the string resource ID for the localized display name of a given language.
+ *
+ * If the specified language is not recognized, defaults to the English string resource.
+ *
+ * @param language The name of the language (e.g., "German", "French").
+ * @return The string resource ID corresponding to the localized name.
+ */
 fun getLanguageStringFromi18n(language: String): Int {
     val languageMap =
         mapOf(
@@ -314,6 +357,15 @@ fun getLanguageStringFromi18n(language: String): Int {
     return languageMap[language] ?: R.string.app__global_english
 }
 
+/**
+ * Builds a list of ScribeItems for the translation source language settings screen.
+ *
+ * This list contains items that allow users to select the source language used in keyboard translation.
+ * When the user selects the source language item, the provided [onTranslationLanguageSelect] callback is triggered.
+ *
+ * @param onTranslationLanguageSelect A lambda function invoked when the user clicks the "Select Source Language" item.
+ * @return A list of [ScribeItem]s to be displayed in the UI.
+ */
 @Composable
 private fun getTranslationSourceLanguageListData(onTranslationLanguageSelect: () -> Unit): List<ScribeItem> {
     val list: MutableList<ScribeItem> = mutableListOf()

diff --git a/app/src/main/java/be/scri/ui/screens/PrivacyPolicyScreen.kt b/app/src/main/java/be/scri/ui/screens/PrivacyPolicyScreen.kt
@@ -57,6 +57,14 @@ fun PrivacyPolicyScreen(
     }
 }
 
+/**
+ * A composable UI layout that displays a scrollable Privacy Policy screen with a title
+ * and a card-wrapped content block.
+ *
+ * @param title The title text displayed at the top of the screen.
+ * @param modifier [Modifier] used to adjust layout behavior or styling from the caller.
+ * @param content A composable lambda that defines the screen's main content, rendered inside a [Card].
+ */
 @Composable
 fun PrivacyPolicyScreenContent(
     title: String,

diff --git a/app/src/main/java/be/scri/ui/screens/ThirdPartyScreen.kt b/app/src/main/java/be/scri/ui/screens/ThirdPartyScreen.kt
@@ -68,6 +68,13 @@ fun ThirdPartyScreen(
     }
 }
 
+/**
+ * A composable UI layout that displays a scrollable screen with a title and a card-wrapped content block.
+ *
+ * @param title The title text displayed at the top of the screen.
+ * @param modifier [Modifier] used to adjust layout behavior or styling from the caller.
+ * @param content A composable lambda that defines the screen's main content, rendered inside a [Card].
+ */
 @Composable
 fun ThirdPartyScreenContent(
     title: String,

diff --git a/app/src/main/java/be/scri/ui/screens/WikimediaScreen.kt b/app/src/main/java/be/scri/ui/screens/WikimediaScreen.kt
@@ -103,6 +103,13 @@ fun WikimediaScreen(
     }
 }
 
+/**
+ * A composable UI layout that displays a scrollable Wikimedia screen with a title and a card-wrapped content block.
+ *
+ * @param title The title text displayed at the top of the screen.
+ * @param modifier [Modifier] used to adjust layout behavior or styling from the caller.
+ * @param content A composable lambda that defines the screen's main content, rendered inside a [Card].
+ */
 @Composable
 fun WikimediaScreenContent(
     title: String,