From a6e22094e8c59866739d427c3a794a177ca26acc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s=20Miguel=20Rubio?= <andres@dhis2.org>
Date: Wed, 16 Oct 2024 14:47:36 +0200
Subject: [PATCH] docs: add TopBar documentation (#316)

---
 .../ui/designsystem/component/TopBar.kt       | 31 +++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/designsystem/src/commonMain/kotlin/org/hisp/dhis/mobile/ui/designsystem/component/TopBar.kt b/designsystem/src/commonMain/kotlin/org/hisp/dhis/mobile/ui/designsystem/component/TopBar.kt
index 3960186bc..ae36fac57 100644
--- a/designsystem/src/commonMain/kotlin/org/hisp/dhis/mobile/ui/designsystem/component/TopBar.kt
+++ b/designsystem/src/commonMain/kotlin/org/hisp/dhis/mobile/ui/designsystem/component/TopBar.kt
@@ -18,6 +18,17 @@ import androidx.compose.ui.Modifier
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.graphics.vector.ImageVector
 
+/**
+ * A composable function that renders a top app bar. Depending on the [type], it can display either a
+ * default aligned top app bar or a center-aligned top app bar.
+ *
+ * @param modifier The [Modifier] to be applied to the TopBar.
+ * @param type The type of the TopBar, either [TopBarType.DEFAULT] for a default aligned top app bar or [TopBarType.CENTERED] for a center-aligned top app bar.
+ * @param navigationIcon A composable function that represents the navigation icon displayed in the TopBar, typically a back arrow or a menu icon.
+ * @param actions A composable function that represents the actions (e.g., icons, menus) displayed on the right side of the TopBar.
+ * @param title A composable function that represents the title content of the TopBar.
+ * @param colors A [TopAppBarColors] that defines the color scheme for the TopBar. Default is [TopAppBarDefaults.topAppBarColors].
+ */
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
 fun TopBar(
@@ -47,6 +58,14 @@ fun TopBar(
     }
 }
 
+/**
+ * A composable function that renders an action icon within the TopBar.
+ *
+ * @param icon The [ImageVector] representing the icon to be displayed.
+ * @param tint The tint color for the icon. Default is [Color.Unspecified].
+ * @param contentDescription A description of the icon for accessibility purposes.
+ * @param onClick The callback to be invoked when the icon is clicked.
+ */
 @Composable
 fun TopBarActionIcon(
     icon: ImageVector,
@@ -66,6 +85,12 @@ fun TopBarActionIcon(
     )
 }
 
+/**
+ * A composable function that renders an icon button which toggles a dropdown menu.
+ *
+ * @param iconTint The tint color for the dropdown icon. Default is [Color.Unspecified].
+ * @param dropDownMenu A composable function that renders the dropdown menu, receiving the current state (shown or hidden) and a callback to dismiss the menu.
+ */
 @Composable
 fun TopBarDropdownMenuIcon(
     iconTint: Color = Color.Unspecified,
@@ -86,6 +111,12 @@ fun TopBarDropdownMenuIcon(
     dropDownMenu(showMenu) { showMenu = false }
 }
 
+/**
+ * Enum class representing the type of the TopBar.
+ *
+ * @property DEFAULT The default TopBar alignment with the title left-aligned.
+ * @property CENTERED A center-aligned TopBar with the title centered.
+ */
 enum class TopBarType {
     DEFAULT,
     CENTERED,