feat: Enhance documentation and code clarity

This commit focuses on improving the application's documentation and overall code clarity. It introduces comprehensive KDoc comments for all classes, methods, and parameters, detailing their purpose, functionality, and expected behavior.

Changes:

-   Added detailed KDoc comments to various classes: `MainActivity`, `AppModule`, `MainViewModel`, `UiState`, `UserRepository`, `RetrofitInstance`, `UserApi`, `TechExactlyApplication`, `CustomNavType`, `Dest`
-   Added detailed KDoc comments to various composables: `UserDetailsTopBar`, `UserDetailsScreenContent`, `HomeScreenContent`, `HomeScreenTopBar`, `UserList`, `UserListItem`, `UserListFooter`, `UserDetailsHeader`, `UserDetailsBody`, `UserDetailsItem`, `UserDetailsItemAddress`, `UserDetailsItemCompany`, `UserDetailsItemAddressRow`, `UserDetailsItemCompanyRow`, `UserDetailsScreen`, `HomeScreen`, `SetupNavGraph`
- Added detailed KDoc comments to data class `User`
- Added detailed KDoc comments to functions `provideRetrofit` and `provideUserApi` in `RetrofitInstance`
- Added detailed KDoc comments to `getUsers` function in `UserRepository` and `UserApi`
- Added detailed KDoc comments to properties `userApi` in `UserRepository` and `MainViewModel`
- Added detailed KDoc comments to properties `uiState` in `MainViewModel`
- Added detailed KDoc comments to `UserType` in `CustomNavType`
- Added detailed KDoc comments to navigation related classes `Dest` and `SetupNavGraph`
- Added detailed KDoc comments to `onCreate` in `TechExactlyApplication`
- Added detailed KDoc comments to `onCreate` in `MainActivity`
- Added detailed KDoc comments to all parameters of all function and composables.

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(