- Added comments for few important methods like mapping weather forecast api responses to domain and then ui model for better understanding.

Author: asadmukhtar28

app/src/main/java/com/asad/weatherapp/data/mapper/WeatherForecastMapper.kt

@@ -13,9 +13,20 @@ import javax.inject.Inject
 
 class WeatherForecastMapper @Inject constructor() :
     ResponseMapper<List<Forecast>, List<WeatherForecastModel>> {
-
+    /**
+     * Maps a list of Forecast API models to the domain-specific WeatherForecastModel.
+     *
+     * @param input List<Forecast> - Raw API data.
+     * @return List<WeatherForecastModel> - Transformed list suitable for UI consumption.
+     */
     override fun map(input: List<Forecast>): List<WeatherForecastModel> = input.toDomainModel()
 
+    /**
+     * Extension function that converts a list of Forecast API objects into domain models.
+     * Groups forecasts by date and extracts a midday representative item for each day.
+     *
+     * @return List<WeatherForecastModel> - Grouped by day, each with a list of time slots.
+     */
     private fun List<Forecast>.toDomainModel(): List<WeatherForecastModel> {
         return this
             .groupBy { it.dtTxt.substring(0, 10) } // group by day
@@ -44,13 +55,25 @@ class WeatherForecastMapper @Inject constructor() :
             }
     }
 
+    /**
+     * Converts raw weather type string from API to domain-specific WeatherType enum.
+     *
+     * @param type String - e.g., "Rain", "Clouds", "Clear"
+     * @return WeatherType - Enum used in domain/UI layer.
+     */
     private fun mapToWeatherType(type: String): WeatherType =
         when {
             type.equals(RAIN, ignoreCase = true) -> WeatherType.RAINY
             type.equals(CLOUDS, ignoreCase = true) -> WeatherType.CLOUDY
             else -> WeatherType.SUNNY
         }
 
+    /**
+     * Maps raw weather condition IDs from API to domain-specific WeatherCondition.
+     *
+     * @param weatherId Int - Numeric ID from OpenWeather API.
+     * @return WeatherCondition - Enum representing weather condition in UI/domain.
+     */
     private fun mapWeatherIcon(weatherId: Int): WeatherCondition {
         return when (weatherId) {
             in 200..232 -> WeatherCondition.THUNDERSTORM

app/src/main/java/com/asad/weatherapp/data/repository/LocationCoordinatesRepositoryImpl.kt

@@ -14,22 +14,46 @@ import javax.inject.Inject
 import kotlin.coroutines.resume
 
 class LocationCoordinatesRepositoryImpl @Inject constructor(
-    @ApplicationContext context: Context
+    @ApplicationContext context: Context,
 ) : LocationCoordinatesRepository {
     private val fusedLocationClient by lazy {
         LocationServices.getFusedLocationProviderClient(
             context
         )
     }
 
+    /**
+     * Suspend function to get the current device location as a [LocationCoordinates] object.
+     *
+     * @OptIn(ExperimentalCoroutinesApi::class) - We are using suspendCancellableCoroutine which is currently experimental.
+     * @RequiresPermission - Ensures caller has ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION.
+     *
+     * @return Result<LocationCoordinates> - Returns success with latitude and longitude or failure if location is unavailable.
+     *
+     * Implementation details:
+     * - Uses suspendCancellableCoroutine to bridge callback-based FusedLocationProviderClient API with coroutines.
+     * - On success:
+     *      - If location is not null, resume coroutine with Result.success(location).
+     *      - If location is null, resume coroutine with Result.failure(ErrorHandler.UnknownError).
+     * - On failure:
+     *      - Wrap the exception in ErrorHandler.UnknownError and resume the coroutine with failure.
+     * - The suspendCancellableCoroutine ensures proper cancellation handling if the coroutine is cancelled before completion.
+     */
     @OptIn(ExperimentalCoroutinesApi::class)
     @RequiresPermission(allOf = [Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION])
     override suspend fun getCurrentLocation(): Result<LocationCoordinates> =
         suspendCancellableCoroutine { continuation ->
             fusedLocationClient.lastLocation
                 .addOnSuccessListener { location ->
                     if (location != null) {
-                        continuation.resume(Result.success(LocationCoordinates(location.latitude, location.longitude)))
+                        continuation.resume(
+                            Result.success(
+                                LocationCoordinates(
+                                    location.latitude,
+                                    location.longitude
+                                )
+                            )
+                        )
                     } else {
                         continuation.resume(Result.failure(ErrorHandler.UnknownError(Exception())))
                     }

app/src/main/java/com/asad/weatherapp/ui/forecast/mapper/WeatherForecastUiMapper.kt

@@ -20,6 +20,18 @@ class WeatherForecastUiMapper @Inject constructor() :
         }
     }
 
+    /**
+     * Maps a list of domain [WeatherForecastModel] objects into a [WeatherForecastUIModel] suitable
+     * for display in the UI.
+     *
+     * @param input List of WeatherForecastModel domain objects.
+     * @return WeatherForecastUIModel containing mapped UI items and the current background.
+     *
+     * Implementation details:
+     * - For each day, finds the closest time slot to the current time.
+     * - Maps each time slot to a [WeatherForecastItemUIModel] containing day name, temperature, and weather icon.
+     * - Determines the overall background based on the first available weather type.
+     */
     override fun map(input: List<WeatherForecastModel>): WeatherForecastUIModel {
         val data = input.map { dto ->
             val currentSlot = closestTimeSlotToCurrentTime(dto.timeSlots)

app/src/main/java/com/asad/weatherapp/utils/CommonUtils.kt

@@ -7,17 +7,51 @@ import java.time.ZoneId
 import java.time.format.TextStyle
 import java.util.Locale
 
+/**
+ * Returns the full day name (e.g., "Monday", "Tuesday") for a given timestamp in seconds.
+ *
+ * @param timestampSeconds The timestamp in seconds since epoch.
+ * @return Day name as a String based on the device's default locale.
+ *
+ * Implementation details:
+ * - Converts epoch seconds to an Instant.
+ * - Converts the Instant to local date-time using the system default timezone.
+ * - Extracts the day of week and returns its full display name according to the default locale.
+ */
 fun getDayName(timestampSeconds: Long): String {
     return Instant.ofEpochSecond(timestampSeconds)
         .atZone(ZoneId.systemDefault())
         .dayOfWeek
         .getDisplayName(TextStyle.FULL, Locale.getDefault())
 }
 
+/**
+ * Finds the closest weather time slot to the current system time.
+ *
+ * @param slots List of [WeatherForecastTimeSlotModel] representing forecasted times.
+ * @return The [WeatherForecastTimeSlotModel] that is closest to the current hour.
+ *
+ * Implementation details:
+ * - Gets the current system hour using LocalTime.now().
+ * - Finds the time slot with the minimum difference between its hour and the current hour.
+ * - If the slots list is empty or minByOrNull returns null, it falls back to the first slot.
+ */
 fun closestTimeSlotToCurrentTime(slots: List<WeatherForecastTimeSlotModel>): WeatherForecastTimeSlotModel {
     val currentHour = LocalTime.now().hour
     return slots.minByOrNull { hourDiff(it, currentHour) } ?: slots.first()
 }
 
+/**
+ * Calculates the absolute difference in hours between a time slot and a reference hour.
+ *
+ * @param slot The [WeatherForecastTimeSlotModel] containing a time string in "HH:mm:ss" format.
+ * @param hour The reference hour (0-23) to compare against.
+ * @return Absolute difference in hours as an Int.
+ *
+ * Implementation details:
+ * - Extracts the hour part from the slot's timeSlot string by taking the substring of first 2 characters.
+ * - Converts it to Int.
+ * - Calculates the absolute difference between the slot hour and the reference hour.
+ */
 private fun hourDiff(slot: WeatherForecastTimeSlotModel, hour: Int): Int =
     kotlin.math.abs(slot.timeSlot.substring(0, 2).toInt() - hour)