Merge pull request #10 from pakohan/feature/documentation

add missing documentation

coverflow/src/main/java/com/pakohan/coverflow/CoverFlow.kt

@@ -17,12 +17,21 @@ import androidx.compose.ui.layout.onGloballyPositioned
 import androidx.compose.ui.platform.LocalDensity
 import androidx.compose.ui.unit.IntSize
 
+/**
+ * CoverFlow implements 🍎 CoverFlow for Jetpack Compose.
+ *
+ * It uses [LazyRow] under the hood.
+ */
 @OptIn(ExperimentalFoundationApi::class)
 @Composable
 fun CoverFlow(
+    /** use it to change the background color */
     modifier: Modifier = Modifier,
+    /** used to make the scrolling accessible to the outside */
     state: CoverFlowState = rememberCoverFlowState(),
+    /** used to configure the design */
     params: CoverFlowParams = CoverFlowParams(),
+    /** used to add list items in the [CoverFlowScope] */
     content: CoverFlowScope.() -> Unit,
 ) {
     var size by remember { mutableStateOf(IntSize.Zero) }

coverflow/src/main/java/com/pakohan/coverflow/CoverFlowScope.kt

@@ -3,7 +3,13 @@ package com.pakohan.coverflow
 import androidx.compose.foundation.lazy.LazyListScope
 import androidx.compose.runtime.Composable
 
+/**
+ * Receiver scope to add elements to the CoverFlow list.
+ */
 interface CoverFlowScope {
+    /**
+     * Add typed items. See [LazyListScope.items]
+     */
     fun <T> items(
         items: List<T>,
         onSelectHandler: (item: T, index: Int) -> Unit = { _: T, _: Int -> },
@@ -12,6 +18,9 @@ interface CoverFlowScope {
         itemContent: @Composable ((item: T) -> Unit),
     )
 
+    /**
+     * Add typed items. See [LazyListScope.items]
+     */
     fun items(
         count: Int,
         onSelectHandler: (index: Int) -> Unit = {},

coverflow/src/main/java/com/pakohan/coverflow/CoverFlowState.kt

@@ -9,6 +9,8 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.launch
 
 /**
+ * Initializes a CoverFlowState.
+ *
  * @param onSelectHandler will be called with -1 as long as the scrolling takes place
  */
 @Composable
@@ -24,18 +26,28 @@ fun rememberCoverFlowState(onSelectHandler: (Int) -> Unit = {}): CoverFlowState
     }
 }
 
+/**
+ * Exposes the scroll state.
+ */
 class CoverFlowState internal constructor(
     internal val lazyListState: LazyListState,
     private val coroutineScope: CoroutineScope,
     private val onSelectHandler: (Int) -> Unit = {},
 ) {
     internal var geometry: Geometry? = null
+
+    /**
+     * Index of the selected item. Set to -1 during scrolling.
+     */
     var selectedIndex: Int = 0
         internal set(it) {
             field = it
             onSelectHandler(it)
         }
 
+    /**
+     * Animated scrolling to the item at index. Will be launched in a [CoroutineScope].
+     */
     fun scrollToItem(
         index: Int,
     ) {

coverflow/src/main/java/com/pakohan/coverflow/DistanceFactor.kt

@@ -10,14 +10,13 @@ import kotlin.math.abs
  */
 interface DistanceFactor {
     /**
-     * factor should return negative values for all elements left of the center and positive for all
+     * Factor should return negative values for all elements left of the center and positive for all
      * elements right of the center.
+     *
      * * It is supposed to be 0 in the center.
      * * It can take values from -1 to 1.
      * * (`factor in -1f..1f`)
      * @param relativeDistance the center to the distance relative to focused covers size.
-     *
-     * this methods name has a great fun-factor
      */
     fun factor(
         relativeDistance: Float,
@@ -45,12 +44,14 @@ class OffsetLinearDistanceFactor(
     }
 
     /**
+     * The factor grows from -1 to 0 to 1. The slope depend on the start and end parameters of the class.
+     *
      * * `relativeDistance < -end -> -1f`
      * * `relativeDistance in -end..-start -> -1f..0f`
      * * `relativeDistance in -start..start -> 0f`
      * * `relativeDistance in start..end -> 0f..1f`
      * * `relativeDistance > end -> 1f`
-     * * `if abs(relativeDistance) in start..end` the factor grows linear.
+     * * `if abs(relativeDistance) in start..end` the factor changes linear.
      */
     override fun factor(
         relativeDistance: Float,
@@ -81,6 +82,10 @@ class OffsetLinearDistanceFactor(
 @Parcelize
 class StaticDistanceFactor(private val factor: Float = 0f) : DistanceFactor,
         Parcelable {
+    /**
+     * Returns the negative factor for a negative distance and the positive factor for a positive
+     * distance. 0 returns 0.
+     */
     override fun factor(
         relativeDistance: Float,
     ): Float {

coverflow/src/main/java/com/pakohan/coverflow/Geometry.kt

@@ -76,12 +76,20 @@ internal class Geometry(
 }
 
 /**
- * params for configuring the coverflow composable.
- * all relevant values are relativ to the dimensions of the CoverFlow composable.
- * This makes sure scaling doesn't destroy how it looks like.
- * All calculations are derived in the following steps:
- *  1. Determine the shorter edge of the CoverFlow composable box.
- *  2. Use DistanceFactor to
+ * Params for configuring the coverflow composable.
+ *
+ * All relevant values are relativ to the dimensions of the CoverFlow composable to make it responsive.
+ * It is based on the shorter of the two sides of the outer component.
+ *
+ * @param size is multiplied with that edge to get the cover size in the middle.
+ * @param offset is multiplied with that edge to get the distance between two covers in the list.
+ * @param distanceFactor calculates how strong the transformations are applied to covers depending
+ * on their distance to the center.
+ * @param angle is the maximum rotation angle.
+ * @param shift is the horizontal shift of the items away from the center. Useful for giving the
+ * center element more space.
+ * @param zoom makes the side elements smaller.
+ * @param mirror acitvates the mirror effect.
  */
 @Immutable
 @Parcelize