From b1acd69a96718756c8b0fa6ae4c9e5dcac1d7dd4 Mon Sep 17 00:00:00 2001 From: Veyndan Stuart Date: Wed, 10 Jan 2024 17:22:52 +0100 Subject: [PATCH 1/3] Document the public API within `redwood-lazylayout-compose` --- .../redwood/lazylayout/compose/LazyDsl.kt | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) diff --git a/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt b/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt index 14389936f7..6c81e10f68 100644 --- a/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt +++ b/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt @@ -22,18 +22,38 @@ import app.cash.redwood.layout.api.Constraint import app.cash.redwood.layout.api.CrossAxisAlignment import app.cash.redwood.ui.Margin +/** + * Receiver scope which is used by [LazyColumn] and [LazyRow]. + */ @LayoutScopeMarker public interface LazyListScope { + /** + * Adds a single item. + * + * @param content the content of the item + */ public fun item( content: @Composable () -> Unit, ) + /** + * Adds a [count] of items. + * + * @param count the items count + * @param itemContent the content displayed by a single item + */ public fun items( count: Int, itemContent: @Composable (index: Int) -> Unit, ) } +/** + * Adds a list of items. + * + * @param items the data list + * @param itemContent the content displayed by a single item + */ public inline fun LazyListScope.items( items: List, crossinline itemContent: @Composable (item: T) -> Unit, @@ -41,6 +61,12 @@ public inline fun LazyListScope.items( itemContent(items[it]) } +/** + * Adds a list of items where the content of an item is aware of its index. + * + * @param items the data list + * @param itemContent the content displayed by a single item + */ public inline fun LazyListScope.itemsIndexed( items: List, crossinline itemContent: @Composable (index: Int, item: T) -> Unit, @@ -50,6 +76,12 @@ public inline fun LazyListScope.itemsIndexed( itemContent(it, items[it]) } +/** + * Adds an array of items. + * + * @param items the data array + * @param itemContent the content displayed by a single item + */ public inline fun LazyListScope.items( items: Array, crossinline itemContent: @Composable (item: T) -> Unit, @@ -59,6 +91,12 @@ public inline fun LazyListScope.items( itemContent(items[it]) } +/** + * Adds an array of items where the content of an item is aware of its index. + * + * @param items the data array + * @param itemContent the content displayed by a single item + */ public inline fun LazyListScope.itemsIndexed( items: Array, crossinline itemContent: @Composable (index: Int, item: T) -> Unit, @@ -71,6 +109,22 @@ public inline fun LazyListScope.itemsIndexed( @RequiresOptIn("This Redwood LazyLayout API is experimental and may change in the future.") public annotation class ExperimentalRedwoodLazyLayoutApi +/** + * The horizontally scrolling list that only composes and lays out the currently visible items. + * The [content] block defines a DSL which allows you to emit items of different types. For + * example you can use [LazyListScope.item] to add a single item and [LazyListScope.items] to add + * a list of items. + * + * @param state the state object to be used to control or observe the list's state + * @param width TODO + * @param height TODO + * @param margin TODO + * @param verticalAlignment the vertical alignment applied to the items + * @param modifier the modifier to apply to this layout + * @param placeholder TODO + * @param content a block which describes the content. Inside this block you can use methods like + * [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items. + */ @Composable public fun LazyRow( state: LazyListState = rememberLazyListState(), @@ -95,6 +149,22 @@ public fun LazyRow( ) } +/** + * TODO + * + * @param refreshing TODO + * @param onRefresh TODO + * @param state the state object to be used to control or observe the list's state + * @param width TODO + * @param height TODO + * @param margin TODO + * @param verticalAlignment the vertical alignment applied to the items + * @param pullRefreshContentColor TODO + * @param modifier the modifier to apply to this layout + * @param placeholder TODO + * @param content a block which describes the content. Inside this block you can use methods like + * [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items. + */ @ExperimentalRedwoodLazyLayoutApi @Composable public fun LazyRow( @@ -126,6 +196,22 @@ public fun LazyRow( ) } +/** + * The vertically scrolling list that only composes and lays out the currently visible items. + * The [content] block defines a DSL which allows you to emit items of different types. For + * example you can use [LazyListScope.item] to add a single item and [LazyListScope.items] to add + * a list of items. + * + * @param state the state object to be used to control or observe the list's state. + * @param width TODO + * @param height TODO + * @param margin TODO + * @param horizontalAlignment the horizontal alignment applied to the items. + * @param modifier the modifier to apply to this layout. + * @param placeholder TODO + * @param content a block which describes the content. Inside this block you can use methods like + * [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items. + */ @Composable public fun LazyColumn( state: LazyListState = rememberLazyListState(), @@ -150,6 +236,22 @@ public fun LazyColumn( ) } +/** + * TODO + * + * @param refreshing TODO + * @param onRefresh TODO + * @param state the state object to be used to control or observe the list's state. + * @param width TODO + * @param height TODO + * @param margin TODO + * @param horizontalAlignment the horizontal alignment applied to the items. + * @param pullRefreshContentColor TODO + * @param modifier the modifier to apply to this layout. + * @param placeholder TODO + * @param content a block which describes the content. Inside this block you can use methods like + * [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items. + */ @ExperimentalRedwoodLazyLayoutApi @Composable public fun LazyColumn( From f5282e96665cd030a4da65e5d3e9c910ab0c9664 Mon Sep 17 00:00:00 2001 From: Veyndan Stuart Date: Thu, 11 Jan 2024 15:02:31 +0100 Subject: [PATCH 2/3] fixup! Document the public API within `redwood-lazylayout-compose` --- .../redwood/lazylayout/compose/LazyDsl.kt | 140 +++++++++++------- .../lazylayout/compose/LazyListState.kt | 8 + 2 files changed, 97 insertions(+), 51 deletions(-) diff --git a/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt b/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt index 6c81e10f68..ad76c109b8 100644 --- a/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt +++ b/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt @@ -30,7 +30,7 @@ public interface LazyListScope { /** * Adds a single item. * - * @param content the content of the item + * @param content The content of the item. */ public fun item( content: @Composable () -> Unit, @@ -39,8 +39,8 @@ public interface LazyListScope { /** * Adds a [count] of items. * - * @param count the items count - * @param itemContent the content displayed by a single item + * @param count The items count. + * @param itemContent The content displayed by a single item. */ public fun items( count: Int, @@ -51,8 +51,8 @@ public interface LazyListScope { /** * Adds a list of items. * - * @param items the data list - * @param itemContent the content displayed by a single item + * @param items The data list. + * @param itemContent The content displayed by a single item. */ public inline fun LazyListScope.items( items: List, @@ -64,8 +64,8 @@ public inline fun LazyListScope.items( /** * Adds a list of items where the content of an item is aware of its index. * - * @param items the data list - * @param itemContent the content displayed by a single item + * @param items The data list. + * @param itemContent The content displayed by a single item. */ public inline fun LazyListScope.itemsIndexed( items: List, @@ -79,8 +79,8 @@ public inline fun LazyListScope.itemsIndexed( /** * Adds an array of items. * - * @param items the data array - * @param itemContent the content displayed by a single item + * @param items The data array. + * @param itemContent The content displayed by a single item. */ public inline fun LazyListScope.items( items: Array, @@ -94,8 +94,8 @@ public inline fun LazyListScope.items( /** * Adds an array of items where the content of an item is aware of its index. * - * @param items the data array - * @param itemContent the content displayed by a single item + * @param items The data array. + * @param itemContent The content displayed by a single item. */ public inline fun LazyListScope.itemsIndexed( items: Array, @@ -115,14 +115,20 @@ public annotation class ExperimentalRedwoodLazyLayoutApi * example you can use [LazyListScope.item] to add a single item and [LazyListScope.items] to add * a list of items. * - * @param state the state object to be used to control or observe the list's state - * @param width TODO - * @param height TODO - * @param margin TODO - * @param verticalAlignment the vertical alignment applied to the items - * @param modifier the modifier to apply to this layout - * @param placeholder TODO - * @param content a block which describes the content. Inside this block you can use methods like + * The purpose of [placeholder] is to define the temporary content of an on-screen item while the + * content of that item (as described by the [content] block) is being retrieved. When the content + * of that item has been retrieved, the [placeholder] is replaced with that of the content. + * + * @param state The state object to be used to control or observe the list's state. + * @param width The width of the list. + * @param height The height of the list. + * @param margin The margin of the list. + * @param verticalAlignment the vertical alignment applied to the items. + * @param modifier The modifier to apply to this layout. + * @param placeholder A block which describes the content of each placeholder item. Note that the + * placeholder block will be invoked multiple times, and assumes that the content and its sizing on + * each invocation is identical to one another. + * @param content A block which describes the content. Inside this block you can use methods like * [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items. */ @Composable @@ -150,19 +156,32 @@ public fun LazyRow( } /** - * TODO + * The horizontally scrolling list that only composes and lays out the currently visible items. + * The [content] block defines a DSL which allows you to emit items of different types. For + * example you can use [LazyListScope.item] to add a single item and [LazyListScope.items] to add + * a list of items. + * + * This function differs from the other [LazyRow] function, in that a refresh indicator is + * conditionally displayed via a vertical swipe gesture when at the beginning of the list. The + * appropriate response to this gesture can be supplied via the [onRefresh] callback. + * + * The purpose of [placeholder] is to define the temporary content of an on-screen item while the + * content of that item (as described by the [content] block) is being retrieved. When the content + * of that item has been retrieved, the [placeholder] is replaced with that of the content. * - * @param refreshing TODO - * @param onRefresh TODO - * @param state the state object to be used to control or observe the list's state - * @param width TODO - * @param height TODO - * @param margin TODO - * @param verticalAlignment the vertical alignment applied to the items - * @param pullRefreshContentColor TODO - * @param modifier the modifier to apply to this layout - * @param placeholder TODO - * @param content a block which describes the content. Inside this block you can use methods like + * @param refreshing Whether or not the list should show the pull-to-refresh indicator. + * @param onRefresh Called when a swipe gesture triggers a pull-to-refresh. + * @param state The state object to be used to control or observe the list's state. + * @param width The width of the list. + * @param height The height of the list. + * @param margin The margin of the list. + * @param verticalAlignment the vertical alignment applied to the items. + * @param pullRefreshContentColor The color of the pull-to-refresh indicator. + * @param modifier The modifier to apply to this layout. + * @param placeholder A block which describes the content of each placeholder item. Note that the + * placeholder block will be invoked multiple times, and assumes that the content and its sizing on + * each invocation is identical to one another. + * @param content A block which describes the content. Inside this block you can use methods like * [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items. */ @ExperimentalRedwoodLazyLayoutApi @@ -202,14 +221,20 @@ public fun LazyRow( * example you can use [LazyListScope.item] to add a single item and [LazyListScope.items] to add * a list of items. * - * @param state the state object to be used to control or observe the list's state. - * @param width TODO - * @param height TODO - * @param margin TODO - * @param horizontalAlignment the horizontal alignment applied to the items. - * @param modifier the modifier to apply to this layout. - * @param placeholder TODO - * @param content a block which describes the content. Inside this block you can use methods like + * The purpose of [placeholder] is to define the temporary content of an on-screen item while the + * content of that item (as described by the [content] block) is being retrieved. When the content + * of that item has been retrieved, the [placeholder] is replaced with that of the content. + * + * @param state The state object to be used to control or observe the list's state. + * @param width The width of the list. + * @param height The height of the list. + * @param margin The margin of the list. + * @param horizontalAlignment The horizontal alignment applied to the items. + * @param modifier The modifier to apply to this layout. + * @param placeholder A block which describes the content of each placeholder item. Note that the + * placeholder block will be invoked multiple times, and assumes that the content and its sizing on + * each invocation is identical to one another. + * @param content A block which describes the content. Inside this block you can use methods like * [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items. */ @Composable @@ -237,19 +262,32 @@ public fun LazyColumn( } /** - * TODO + * The vertically scrolling list that only composes and lays out the currently visible items. + * The [content] block defines a DSL which allows you to emit items of different types. For + * example you can use [LazyListScope.item] to add a single item and [LazyListScope.items] to add + * a list of items. + * + * This function differs from the other [LazyColumn] function, in that a refresh indicator is + * conditionally displayed via a vertical swipe gesture when at the beginning of the list. The + * appropriate response to this gesture can be supplied via the [onRefresh] callback. + * + * The purpose of [placeholder] is to define the temporary content of an on-screen item while the + * content of that item (as described by the [content] block) is being retrieved. When the content + * of that item has been retrieved, the [placeholder] is replaced with that of the content. * - * @param refreshing TODO - * @param onRefresh TODO - * @param state the state object to be used to control or observe the list's state. - * @param width TODO - * @param height TODO - * @param margin TODO - * @param horizontalAlignment the horizontal alignment applied to the items. - * @param pullRefreshContentColor TODO - * @param modifier the modifier to apply to this layout. - * @param placeholder TODO - * @param content a block which describes the content. Inside this block you can use methods like + * @param refreshing Whether or not the list should show the pull-to-refresh indicator. + * @param onRefresh Called when a swipe gesture triggers a pull-to-refresh. + * @param state The state object to be used to control or observe the list's state. + * @param width The width of the list. + * @param height The height of the list. + * @param margin The margin of the list. + * @param horizontalAlignment The horizontal alignment applied to the items. + * @param pullRefreshContentColor The color of the pull-to-refresh indicator. + * @param modifier The modifier to apply to this layout. + * @param placeholder A block which describes the content of each placeholder item. Note that the + * placeholder block will be invoked multiple times, and assumes that the content and its sizing on + * each invocation is identical to one another. + * @param content A block which describes the content. Inside this block you can use methods like * [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items. */ @ExperimentalRedwoodLazyLayoutApi diff --git a/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyListState.kt b/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyListState.kt index dcf78cfdf4..573eed81ef 100644 --- a/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyListState.kt +++ b/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyListState.kt @@ -25,6 +25,9 @@ import app.cash.redwood.lazylayout.api.ScrollItemIndex private const val DEFAULT_PRELOAD_ITEM_COUNT = 15 +/** + * Creates a [LazyListState] that is remembered across compositions. + */ @Composable public fun rememberLazyListState(): LazyListState { return rememberSaveable(saver = saver) { @@ -42,6 +45,11 @@ private val saver: Saver = Saver( }, ) +/** + * A state object that can be hoisted to control and observe scrolling. + * + * In most cases, this will be created via [rememberLazyListState]. + */ public open class LazyListState { /** * Update this to trigger a programmatic scroll. This may be updated multiple times, including From c656faebab4878c0a19434ca906cd0a7970d15d5 Mon Sep 17 00:00:00 2001 From: Veyndan Stuart Date: Mon, 15 Jan 2024 15:37:22 +0100 Subject: [PATCH 3/3] fixup! Document the public API within `redwood-lazylayout-compose` --- .../redwood/lazylayout/compose/LazyDsl.kt | 36 ++++++++++++------- 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt b/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt index ad76c109b8..4bbce1f326 100644 --- a/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt +++ b/redwood-lazylayout-compose/src/commonMain/kotlin/app/cash/redwood/lazylayout/compose/LazyDsl.kt @@ -120,9 +120,12 @@ public annotation class ExperimentalRedwoodLazyLayoutApi * of that item has been retrieved, the [placeholder] is replaced with that of the content. * * @param state The state object to be used to control or observe the list's state. - * @param width The width of the list. - * @param height The height of the list. - * @param margin The margin of the list. + * @param width Sets whether the row's width will wrap its contents ([Constraint.Wrap]) or match the + * width of its parent ([Constraint.Fill]). + * @param height Sets whether the row's height will wrap its contents ([Constraint.Wrap]) or match + * the height of its parent ([Constraint.Fill]). + * @param margin Applies margin (space) around the list. This can also be applied to an individual + * item using `Modifier.margin`. * @param verticalAlignment the vertical alignment applied to the items. * @param modifier The modifier to apply to this layout. * @param placeholder A block which describes the content of each placeholder item. Note that the @@ -172,9 +175,12 @@ public fun LazyRow( * @param refreshing Whether or not the list should show the pull-to-refresh indicator. * @param onRefresh Called when a swipe gesture triggers a pull-to-refresh. * @param state The state object to be used to control or observe the list's state. - * @param width The width of the list. - * @param height The height of the list. - * @param margin The margin of the list. + * @param width Sets whether the row's width will wrap its contents ([Constraint.Wrap]) or match the + * width of its parent ([Constraint.Fill]). + * @param height Sets whether the row's height will wrap its contents ([Constraint.Wrap]) or match + * the height of its parent ([Constraint.Fill]). + * @param margin Applies margin (space) around the list. This can also be applied to an individual + * item using `Modifier.margin`. * @param verticalAlignment the vertical alignment applied to the items. * @param pullRefreshContentColor The color of the pull-to-refresh indicator. * @param modifier The modifier to apply to this layout. @@ -226,9 +232,12 @@ public fun LazyRow( * of that item has been retrieved, the [placeholder] is replaced with that of the content. * * @param state The state object to be used to control or observe the list's state. - * @param width The width of the list. - * @param height The height of the list. - * @param margin The margin of the list. + * @param width Sets whether the row's width will wrap its contents ([Constraint.Wrap]) or match the + * width of its parent ([Constraint.Fill]). + * @param height Sets whether the row's height will wrap its contents ([Constraint.Wrap]) or match + * the height of its parent ([Constraint.Fill]). + * @param margin Applies margin (space) around the list. This can also be applied to an individual + * item using `Modifier.margin`. * @param horizontalAlignment The horizontal alignment applied to the items. * @param modifier The modifier to apply to this layout. * @param placeholder A block which describes the content of each placeholder item. Note that the @@ -278,9 +287,12 @@ public fun LazyColumn( * @param refreshing Whether or not the list should show the pull-to-refresh indicator. * @param onRefresh Called when a swipe gesture triggers a pull-to-refresh. * @param state The state object to be used to control or observe the list's state. - * @param width The width of the list. - * @param height The height of the list. - * @param margin The margin of the list. + * @param width Sets whether the row's width will wrap its contents ([Constraint.Wrap]) or match the + * width of its parent ([Constraint.Fill]). + * @param height Sets whether the row's height will wrap its contents ([Constraint.Wrap]) or match + * the height of its parent ([Constraint.Fill]). + * @param margin Applies margin (space) around the list. This can also be applied to an individual + * item using `Modifier.margin`. * @param horizontalAlignment The horizontal alignment applied to the items. * @param pullRefreshContentColor The color of the pull-to-refresh indicator. * @param modifier The modifier to apply to this layout.