Merge pull request #8 from CGreenP/dev

CGreenP · web-flow · commit cc4bbe6f059f · 2025-04-05T19:33:36.000+05:30
feat: Enhance documentation and code clarity
diff --git a/app/src/main/java/com/example/techexactly/MainActivity.kt b/app/src/main/java/com/example/techexactly/MainActivity.kt
@@ -13,6 +13,17 @@ import androidx.navigation.compose.rememberNavController
 import com.example.techexactly.ui.theme.TechExactlyTheme
 import com.example.techexactly.view.navigation.SetupNavGraph
 
+/**
+ * The main activity of the TechExactly application.
+ *
+ * This activity serves as the entry point for the application.  It handles the following:
+ * - Sets up the splash screen with a custom exit animation.
+ * - Enables edge-to-edge display for a more immersive experience.
+ * - Sets the content of the activity to a Compose-based UI, including:
+ *   - A navigation controller to manage screen transitions.
+ *   - A navigation graph to define the app's structure.
+ *   - The application's theme.
+ */
 class MainActivity : ComponentActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
diff --git a/app/src/main/java/com/example/techexactly/TechExactlyApplication.kt b/app/src/main/java/com/example/techexactly/TechExactlyApplication.kt
@@ -7,6 +7,11 @@ import org.koin.android.ext.koin.androidLogger
 import org.koin.core.context.startKoin
 import org.koin.core.logger.Level
 
+/**
+ *  The main application class for the TechExactly application.  This class
+ *  initializes Koin, the dependency injection framework, during the application's
+ *  `onCreate` lifecycle event.
+ */
 class TechExactlyApplication : Application() {
     override fun onCreate() {
         super.onCreate()
diff --git a/app/src/main/java/com/example/techexactly/di/AppModule.kt b/app/src/main/java/com/example/techexactly/di/AppModule.kt
@@ -7,6 +7,14 @@ import com.example.techexactly.viewmodel.MainViewModel
 import org.koin.core.module.dsl.viewModelOf
 import org.koin.dsl.module
 
+/**
+ * Koin module defining dependencies related to the application's core functionalities.
+ * It includes:
+ *  - Retrofit instance for network communication.
+ *  - User API interface implementation.
+ *  - UserRepository instance for accessing user data.
+ *  - MainViewModel instance for managing the main screen's data and logic.
+ */
 val appModule = module {
     single { provideRetrofit() }
     single { provideUserApi(get()) }
diff --git a/app/src/main/java/com/example/techexactly/model/dataclass/User.kt b/app/src/main/java/com/example/techexactly/model/dataclass/User.kt
@@ -2,6 +2,18 @@ package com.example.techexactly.model.dataclass
 
 import kotlinx.serialization.Serializable
 
+/**
+ * Represents a user with their personal and professional information.
+ *
+ * @property id The unique identifier of the user.
+ * @property name The full name of the user.
+ * @property username The username or alias of the user.
+ * @property email The email address of the user.
+ * @property address The address details of the user, including street, city, etc.
+ * @property phone The phone number of the user.
+ * @property website The website associated with the user.
+ * @property company The company details of the user, including name and other information.
+ */
 @Serializable
 data class User(
     val id: Long,
diff --git a/app/src/main/java/com/example/techexactly/model/network/RetrofitInstance.kt b/app/src/main/java/com/example/techexactly/model/network/RetrofitInstance.kt
@@ -8,20 +8,39 @@ import retrofit2.converter.gson.GsonConverterFactory
 
 private const val BASE_URL = "https://jsonplaceholder.typicode.com/"
 
+/**
+ * Provides a configured Retrofit instance for making network requests.
+ *
+ * This function sets up a Retrofit client with the following features:
+ * - **Base URL:** Uses the [BASE_URL] constant as the base URL for all requests.  Ensure this constant is defined in your project.
+ * - **OkHttpClient:**  Uses an OkHttpClient to handle the network communication, configured with:
+ *   - **Logging Interceptor:**  An [HttpLoggingInterceptor] that logs the request and response bodies at the `BODY` level, aiding in debugging.  **Note:**  This should be removed or adjusted for production builds.
+ * - **Gson Converter Factory:** Uses a [GsonConverterFactory] to serialize and deserialize JSON responses using the Gson library.  The Gson instance is configured to be lenient, allowing for some flexibility in the expected JSON structure.
+ *
+ * @return A configured [Retrofit] instance ready for creating API interfaces.
+ */
 fun provideRetrofit(): Retrofit {
     val loggingInterceptor = HttpLoggingInterceptor().apply {
         level = HttpLoggingInterceptor.Level.BODY
     }
     val okHttpClient = OkHttpClient.Builder().addInterceptor(loggingInterceptor).build()
     val gson = GsonBuilder().setLenient().create()
 
-    return Retrofit.Builder()
-        .baseUrl(BASE_URL)
-        .client(okHttpClient)
-        .addConverterFactory(GsonConverterFactory.create(gson))
-        .build()
+    return Retrofit.Builder().baseUrl(BASE_URL).client(okHttpClient)
+        .addConverterFactory(GsonConverterFactory.create(gson)).build()
 }
 
+/**
+ * Provides an instance of the [UserApi] interface.
+ *
+ * This function uses a pre-configured [Retrofit] instance to create an implementation of the [UserApi] interface,
+ * which is used to interact with the user-related endpoints of the API.  This abstraction allows for easier testing
+ * and decoupling of the network layer from the rest of the application.
+ *
+ * @param retrofit A configured [Retrofit] instance.  This instance should already be configured with the base URL,
+ *                  converter factories (e.g., GsonConverterFactory), and any necessary interceptors (e.g., for authentication).
+ * @return An instance of [UserApi] that can be used to make API calls related to users.
+ */
 fun provideUserApi(retrofit: Retrofit): UserApi {
     return retrofit.create(UserApi::class.java)
 }
diff --git a/app/src/main/java/com/example/techexactly/model/network/UserApi.kt b/app/src/main/java/com/example/techexactly/model/network/UserApi.kt
@@ -4,6 +4,9 @@ import com.example.techexactly.model.dataclass.User
 import retrofit2.Response
 import retrofit2.http.GET
 
+/**
+ * Defines the API endpoints for interacting with user data.
+ */
 interface UserApi {
     @GET("/users")
     suspend fun getUsers(): Response<List<User>>
diff --git a/app/src/main/java/com/example/techexactly/model/repository/UserRepository.kt b/app/src/main/java/com/example/techexactly/model/repository/UserRepository.kt
@@ -7,6 +7,12 @@ import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.flow
 import kotlinx.coroutines.flow.flowOn
 
+/**
+ * Repository class responsible for managing user data.
+ * It interacts with the [UserApi] to fetch user information from a remote source.
+ *
+ * @property userApi The API interface used to communicate with the user data source.
+ */
 class UserRepository(private val userApi: UserApi) {
     fun getUsers(): Flow<Result<List<User>>> = flow {
         try {
diff --git a/app/src/main/java/com/example/techexactly/view/home/HomeScreen.kt b/app/src/main/java/com/example/techexactly/view/home/HomeScreen.kt
@@ -18,6 +18,12 @@ import com.example.techexactly.model.dataclass.User
 import com.example.techexactly.viewmodel.MainViewModel
 import org.koin.androidx.compose.koinViewModel
 
+/**
+ * The main screen of the application, displaying a list of users and a search bar.
+ *
+ * @param onUserClicked Callback function invoked when a user item in the list is clicked.  It takes a [User] object as a parameter representing the clicked user.
+ * @param mainViewModel The [MainViewModel] instance used to manage the data and state for the screen, defaults to an instance retrieved from Koin.
+ */
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
 fun HomeScreen(
diff --git a/app/src/main/java/com/example/techexactly/view/home/HomeScreenContent.kt b/app/src/main/java/com/example/techexactly/view/home/HomeScreenContent.kt
@@ -26,6 +26,12 @@ import com.example.techexactly.model.dataclass.User
 import com.example.techexactly.viewmodel.MainViewModel
 import com.example.techexactly.viewmodel.UiState
 
+/**
+ * Displays the content of the Home Screen, handling different UI states (Loading, Success, Error).
+ *
+ * @param onUserClicked Callback function triggered when a user in the list is clicked. It receives the clicked [User] as a parameter.
+ * @param mainViewModel The [MainViewModel] instance providing the current UI state.
+ */
 @Composable
 fun HomeScreenContent(
     onUserClicked: (User) -> Unit, mainViewModel: MainViewModel
diff --git a/app/src/main/java/com/example/techexactly/view/home/HomeScreenTopBar.kt b/app/src/main/java/com/example/techexactly/view/home/HomeScreenTopBar.kt
@@ -35,6 +35,18 @@ import androidx.compose.ui.tooling.preview.Preview
 import androidx.compose.ui.unit.dp
 import com.example.techexactly.R
 
+/**
+ * Composable function for the top app bar of the Home Screen.
+ *
+ * This composable displays a centered top app bar with the app logo, title, subtitle, and a search bar.
+ * The search bar can be toggled via a search icon button, and it filters the displayed content based on user input.
+ *
+ * @param title The main title to display in the top bar.
+ * @param subtitle The subtitle to display below the main title.
+ * @param scrollBehavior The scroll behavior for the top app bar, handling scrolling effects.
+ * @param searchQuery The current search query string. Defaults to an empty string.
+ * @param onSearchQueryChanged Callback function invoked when the search query changes. It receives the new query string as a parameter.
+ */
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
 fun HomeScreenTopBar(
@@ -76,16 +88,17 @@ fun HomeScreenTopBar(
                 }
             }
         }, navigationIcon = {
-                Image(
-                    modifier = Modifier.padding(start = 8.dp).size(24.dp),
-                    painter = painterResource(id = R.drawable.app_logo),
-                    contentDescription = null,
-                    colorFilter = ColorFilter.tint(
-                        MaterialTheme.colorScheme.onSurface
-                    )
+            Image(
+                modifier = Modifier
+                    .padding(start = 8.dp)
+                    .size(24.dp),
+                painter = painterResource(id = R.drawable.app_logo),
+                contentDescription = null,
+                colorFilter = ColorFilter.tint(
+                    MaterialTheme.colorScheme.onSurface
                 )
-            },
-            scrollBehavior = scrollBehavior
+            )
+        }, scrollBehavior = scrollBehavior
         )
         AnimatedVisibility(visible = showSearchBar) {
             DockedSearchBar(
diff --git a/app/src/main/java/com/example/techexactly/view/home/UserList.kt b/app/src/main/java/com/example/techexactly/view/home/UserList.kt
@@ -26,6 +26,12 @@ import com.example.techexactly.model.dataclass.Company
 import com.example.techexactly.model.dataclass.Geo
 import com.example.techexactly.model.dataclass.User
 
+/**
+ * Composable function to display a list of users.
+ *
+ * @param users A list of [User] objects to be displayed.  If the list is empty, a message indicating "No Users Found" will be displayed.
+ * @param onUserClicked A lambda function to be called when a user item is clicked.  It takes a [User] object as a parameter.
+ */
 @Composable
 fun UserList(users: List<User>, onUserClicked: (User) -> Unit) {
     LazyColumn(
diff --git a/app/src/main/java/com/example/techexactly/view/home/UserListFooter.kt b/app/src/main/java/com/example/techexactly/view/home/UserListFooter.kt
@@ -14,6 +14,14 @@ import androidx.compose.ui.Modifier
 import androidx.compose.ui.tooling.preview.Preview
 import androidx.compose.ui.unit.dp
 
+/**
+ * Composable function that displays a footer at the end of a user list.
+ *
+ * This footer includes a horizontal divider, a "End of the list" text,
+ * and spacing for visual separation.  It is designed to be placed
+ * at the bottom of a scrollable user list to indicate the end of the data.
+ *
+ */
 @Composable
 fun UserListFooter() {
     Column(
diff --git a/app/src/main/java/com/example/techexactly/view/home/UserListItem.kt b/app/src/main/java/com/example/techexactly/view/home/UserListItem.kt
@@ -28,6 +28,12 @@ import com.example.techexactly.model.dataclass.Company
 import com.example.techexactly.model.dataclass.Geo
 import com.example.techexactly.model.dataclass.User
 
+/**
+ * Composable function to display a user item in a list.
+ *
+ * @param user The [User] data to display.
+ * @param onUserClicked Callback function to be invoked when the user item is clicked.  It receives the clicked [User] as a parameter.
+ */
 @Composable
 fun UserListItem(user: User, onUserClicked: (User) -> Unit) {
     ElevatedCard(
diff --git a/app/src/main/java/com/example/techexactly/view/navigation/CustomNavType.kt b/app/src/main/java/com/example/techexactly/view/navigation/CustomNavType.kt
@@ -6,6 +6,11 @@ import androidx.navigation.NavType
 import com.example.techexactly.model.dataclass.User
 import kotlinx.serialization.json.Json
 
+/**
+ *  Custom Navigation Type for complex objects (in this case, a User object).  Allows passing
+ *  objects as navigation arguments instead of just simple types.  Uses Kotlin Serialization
+ *  to encode/decode the object as a JSON string for storage in a Bundle or URI.
+ */
 object CustomNavType {
     val UserType = object : NavType<User>(
         isNullableAllowed = false
diff --git a/app/src/main/java/com/example/techexactly/view/navigation/NavGraph.kt b/app/src/main/java/com/example/techexactly/view/navigation/NavGraph.kt
@@ -11,6 +11,16 @@ import com.example.techexactly.view.user.UserDetailsScreen
 import kotlin.reflect.typeOf
 
 
+/**
+ * Sets up the navigation graph for the application.
+ *
+ * This function defines the composable structure for navigating between different screens in the app.
+ * It uses a [NavHost] to manage the navigation stack and defines routes for the [HomeScreen] and
+ * [UserDetailsScreen].
+ *
+ * @param navController The [NavHostController] responsible for managing navigation within the app.  This controller
+ *                      is typically created in the main activity or a higher-level composable and passed down to this function.
+ */
 @Composable
 fun SetupNavGraph(
     navController: NavHostController
diff --git a/app/src/main/java/com/example/techexactly/view/navigation/Screens.kt b/app/src/main/java/com/example/techexactly/view/navigation/Screens.kt
@@ -3,6 +3,13 @@ package com.example.techexactly.view.navigation
 import com.example.techexactly.model.dataclass.User
 import kotlinx.serialization.Serializable
 
+/**
+ * Sealed class representing the different destinations within the application.  This allows for type-safe navigation
+ * between screens.  Each subclass of `Dest` represents a unique screen, and can optionally contain data needed to
+ * display that screen (e.g., user details).  The use of `@Serializable` on both the sealed class and its data subclasses
+ * enables serialization and deserialization, allowing for persistence of navigation state (e.g., for deep linking or
+ * restoring state after app termination).
+ */
 sealed class Dest {
 
     @Serializable
diff --git a/app/src/main/java/com/example/techexactly/view/user/UserDetailsBody.kt b/app/src/main/java/com/example/techexactly/view/user/UserDetailsBody.kt
diff --git a/app/src/main/java/com/example/techexactly/view/user/UserDetailsHeader.kt b/app/src/main/java/com/example/techexactly/view/user/UserDetailsHeader.kt
diff --git a/app/src/main/java/com/example/techexactly/view/user/UserDetailsScreen.kt b/app/src/main/java/com/example/techexactly/view/user/UserDetailsScreen.kt
diff --git a/app/src/main/java/com/example/techexactly/view/user/UserDetailsScreenContent.kt b/app/src/main/java/com/example/techexactly/view/user/UserDetailsScreenContent.kt
diff --git a/app/src/main/java/com/example/techexactly/view/user/UserDetailsTopBar.kt b/app/src/main/java/com/example/techexactly/view/user/UserDetailsTopBar.kt
diff --git a/app/src/main/java/com/example/techexactly/viewmodel/MainViewModel.kt b/app/src/main/java/com/example/techexactly/viewmodel/MainViewModel.kt
diff --git a/app/src/main/java/com/example/techexactly/viewmodel/UiState.kt b/app/src/main/java/com/example/techexactly/viewmodel/UiState.kt
