Document TimePicker and ClockPicker Composable and their util classes, functions

picker/src/main/java/org/fknives/android/compose/picker/time/DefaultAMPMList.kt

@@ -5,10 +5,16 @@ import androidx.compose.runtime.remember
 import java.text.DateFormatSymbols
 import java.util.Locale
 
+/**
+ * Returns Default AM, PM texts for given [locale].
+ */
 fun defaultAmPmStrings(locale: Locale = Locale.getDefault()) =
     DateFormatSymbols.getInstance(locale).amPmStrings.toList()
 
+/**
+ * Caches the [defaultAmPmStrings].
+ */
 @Composable
 fun rememberDefaultAMPMList(locale: Locale = Locale.getDefault()) = remember(locale) {
-    DateFormatSymbols.getInstance(locale).amPmStrings.toList()
+    defaultAmPmStrings(locale = locale)
 }

picker/src/main/java/org/fknives/android/compose/picker/time/SelectedTime.kt

@@ -3,6 +3,9 @@ package org.fknives.android.compose.picker.time
 import androidx.compose.runtime.Immutable
 import java.util.Calendar
 
+/**
+ * Selection state object, representing current selection of [TimePicker]
+ */
 @Immutable
 data class SelectedTime(
     val hour: Int,
@@ -11,6 +14,10 @@ data class SelectedTime(
 ) {
 
     companion object {
+        /**
+         * Creates [SelectedTime] from the given unix [time] stamp.
+         * Defaults to Current Time.
+         */
         fun get(time: Long = System.currentTimeMillis()): SelectedTime {
             val calendar = Calendar.getInstance()
             calendar.timeInMillis = time

picker/src/main/java/org/fknives/android/compose/picker/time/TimePicker.kt

@@ -8,12 +8,25 @@ import org.fknives.android.compose.picker.number.NumberPickerConfig
 import org.fknives.android.compose.picker.number.rememberNumberPickerScope
 import org.fknives.android.compose.picker.number.rememberNumberPickerState
 
+/**
+ * Sets up Time Pickers.
+ * Expected to contain an Hour, Minute and AM/PM Picker, respectively, Number, Number and TextPicker.
+ *
+ * Creates a [TimePickerScope] which then is feeded to [timePickers].
+ *
+ * @param timePickersMinWidth MinWidth given for each TimePicker.
+ * @param selectedTime currently selected [SelectedTime]
+ * @param onSelectedTimeChanged notified when [SelectedTime] should be changes by User Actions.
+ * @param amPm the list of translated texts for "AM" and "PM". Expected order is AM,PM.
+ * @param timePickers the actual Composable for TimePickers.
+ * *Note: Check Defaults for customization: [StandardTimePickers].
+ */
 @Composable
 fun TimePicker(
     timePickersMinWidth: Dp = 40.dp,
     selectedTime: SelectedTime,
-    amPm: List<String> = rememberDefaultAMPMList(),
     onSelectedTimeChanged: (SelectedTime) -> Unit,
+    amPm: List<String> = rememberDefaultAMPMList(),
     timePickers: @Composable (TimePickerScope) -> Unit = { StandardTimePickers(it) }
 ) {
     val hourConfig = remember { NumberPickerConfig.configHourPicker12 }

picker/src/main/java/org/fknives/android/compose/picker/time/TimePickerScope.kt

@@ -7,6 +7,11 @@ import androidx.compose.ui.unit.Dp
 import org.fknives.android.compose.picker.number.NumberPickerScope
 import org.fknives.android.compose.picker.text.util.TextPickerDefaults
 
+/**
+ * Scope setup from [TimePicker].
+ *
+ * Contains all the Values for the respective Hour, Minute and AMorPM Pickers.
+ */
 @Immutable
 interface TimePickerScope {
     val timePickerMinWidth: Dp
@@ -15,6 +20,9 @@ interface TimePickerScope {
     val amORpmPickerScope: AMorPMPickerScope
 }
 
+/**
+ * Data class implementation of [TimePickerScope]
+ */
 @Immutable
 data class TimePickerScopeImpl(
     override val timePickerMinWidth: Dp,
@@ -23,6 +31,10 @@ data class TimePickerScopeImpl(
     override val amORpmPickerScope: AMorPMPickerScope
 ) : TimePickerScope
 
+/**
+ * Intended scope for AMorPM Picker.
+ * Contained within [TimePickerScope]
+ */
 @Immutable
 interface AMorPMPickerScope {
     val listOfAMorPM: List<String>
@@ -31,6 +43,9 @@ interface AMorPMPickerScope {
     val onIndexDifferenceChanging: (Int) -> Unit
 }
 
+/**
+ * Data class implementation of [AMorPMPickerScope]
+ */
 @Immutable
 data class AMorPMPickerScopeImpl(
     override val listOfAMorPM: List<String>,
@@ -39,6 +54,9 @@ data class AMorPMPickerScopeImpl(
     override val onIndexDifferenceChanging: (Int) -> Unit = TextPickerDefaults.onIndexDifferenceChanging
 ) : AMorPMPickerScope
 
+/**
+ * Caching function for [AMorPMPickerScope]
+ */
 @Composable
 fun rememberAMorPMPickerScope(
     listOfAMorPM: List<String>,
@@ -57,6 +75,9 @@ fun rememberAMorPMPickerScope(
     }
 }
 
+/**
+ * Caching function for [TimePickerScope]
+ */
 @Composable
 fun rememberTimePickerScope(
     timePickerMinWidth: Dp,

picker/src/main/java/org/fknives/android/compose/picker/time/TimePickerScopeExtensions.kt

@@ -10,6 +10,11 @@ import org.fknives.android.compose.picker.number.CustomInnerTextPicker
 import org.fknives.android.compose.picker.text.TextPicker
 import org.fknives.android.compose.picker.text.util.TextPickerDefaults
 
+/**
+ * Default Pickers for [TimePicker].
+ *
+ * Gets values from [scope] and creates the respective Pickers.
+ */
 @Composable
 fun StandardTimePickers(scope: TimePickerScope) {
     Row {
@@ -21,6 +26,11 @@ fun StandardTimePickers(scope: TimePickerScope) {
     }
 }
 
+/**
+ * Default Hour Picker for [TimePicker]
+ *
+ * Gets values from [TimePickerScope.hoursPickerScope].
+ */
 @Composable
 fun TimePickerScope.HourPicker(
     modifier: Modifier = Modifier,
@@ -36,6 +46,12 @@ fun TimePickerScope.HourPicker(
     }
 }
 
+/**
+ * Default Hour Picker for [TimePicker]
+ *
+ * Gets values from [TimePickerScope.minutesPickerScope].
+ */
+
 @Composable
 fun TimePickerScope.MinutePicker(
     modifier: Modifier = Modifier,
@@ -51,6 +67,11 @@ fun TimePickerScope.MinutePicker(
     }
 }
 
+/**
+ * Default Hour Picker for [TimePicker]
+ *
+ * Gets values from [TimePickerScope.amORpmPickerScope].
+ */
 @Composable
 fun TimePickerScope.IsAMorPMPicker(
     modifier: Modifier = Modifier,

picker/src/main/java/org/fknives/android/compose/picker/time/clock/ClockPicker.kt

@@ -19,9 +19,28 @@ import org.fknives.android.compose.picker.time.rememberDefaultAMPMList
 import org.fknives.android.compose.picker.time.rememberTimePickerScope
 import kotlin.math.abs
 
+/**
+ * Custom [TimePicker][org.fknives.android.compose.picker.time.TimePicker] implementation.
+ *
+ * Main difference is that this implementation contains additional interactions between the elements:
+ * - When Hour Rotates Around   (1 -by decrease-> 12 or 12 -by increase-> 1) the AM/PM Picker is automatically updated.
+ * - When Minute Rotates Around (0 -by decrease-> 59 or 59 by increase-> 0) the Hour Picker is updated
+ * (if that rotates around the AM/PM also)
+ *
+ * These updates are just on the UI while selecting, they become permanent, aka [onSelectedTimeChanged] notified only when the user lets go.
+ *
+ * Creates a Custom Implementation [TimePickerScope] which then is feeded to [timePickers].
+ *
+ * @param timePickersMinWidth MinWidth given for each TimePicker.
+ * @param selectedTime currently selected [SelectedTime]
+ * @param onSelectedTimeChanged notified when [SelectedTime] should be changes by User Actions.
+ * @param amPm the list of translated texts for "AM" and "PM". Expected order is AM,PM.
+ * @param timePickers the actual Composable for TimePickers.
+ * *Note: Check Defaults for customization: [StandardTimePickers].
+ */
 @Composable
 fun ClockTimePicker(
-    timePickerMinWidth: Dp = 40.dp,
+    timePickersMinWidth: Dp = 40.dp,
     selectedTime: SelectedTime,
     amPm: List<String> = rememberDefaultAMPMList(),
     onSelectedTimeChanged: (SelectedTime) -> Unit,
@@ -80,7 +99,7 @@ fun ClockTimePicker(
     )
 
     val scope = rememberTimePickerScope(
-        timePickerMinWidth = timePickerMinWidth,
+        timePickerMinWidth = timePickersMinWidth,
         hoursPickerScope = hourScope,
         minutesPickerScope = minutesScope,
         amORpmPickerScope = amORpmScope