Merge pull request #8 from CGreenP/dev

feat: Enhance documentation and code clarity

Author: CGreenP

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)

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

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

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,

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

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

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 {

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(

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

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(