Update docs for text consistency and clarity.

In particular, focus has been placed on ensuring
common parameters across components use the same
wording to describe their purpose.

Bug: b/227511404
Test: n/a
Change-Id: I00d99a663d26216a6509985e1aa0157ebb724b84

diff --git a/compose/material3/material3/src/androidMain/kotlin/androidx/compose/material3/AndroidAlertDialog.android.kt b/compose/material3/material3/src/androidMain/kotlin/androidx/compose/material3/AndroidAlertDialog.android.kt
index c312933..edb3dca 100644
--- a/compose/material3/material3/src/androidMain/kotlin/androidx/compose/material3/AndroidAlertDialog.android.kt
+++ b/compose/material3/material3/src/androidMain/kotlin/androidx/compose/material3/AndroidAlertDialog.android.kt

@@ -44,28 +44,29 @@
  * Usage with a "Hero" icon:
  * @sample androidx.compose.material3.samples.AlertDialogWithIconSample
  *
- * @param onDismissRequest Executes when the user tries to dismiss the Dialog by clicking outside
+ * @param onDismissRequest called when the user tries to dismiss the Dialog by clicking outside
  * or pressing the back button. This is not called when the dismiss button is clicked.
- * @param confirmButton A button which is meant to confirm a proposed action, thus resolving
- * what triggered the dialog. The dialog does not set up any events for this button so they need
- * to be set up by the caller.
- * @param modifier Modifier to be applied to the layout of the dialog.
- * @param dismissButton A button which is meant to dismiss the dialog. The dialog does not set up
- * any events for this button so they need to be set up by the caller.
- * @param icon An optional icon that will appear above the [title] or above the [text], in case a
+ * @param confirmButton button which is meant to confirm a proposed action, thus resolving what
+ * triggered the dialog. The dialog does not set up any events for this button so they need to be
+ * set up by the caller.
+ * @param modifier the [Modifier] to be applied to this dialog
+ * @param dismissButton button which is meant to dismiss the dialog. The dialog does not set up any
+ * events for this button so they need to be set up by the caller.
+ * @param icon optional icon that will appear above the [title] or above the [text], in case a
  * title was not provided.
- * @param title The title of the Dialog which should specify the purpose of the Dialog. The title
- * is not mandatory, because there may be sufficient information inside the [text].
- * @param text The text which presents the details regarding the Dialog's purpose.
- * @param shape Defines the Dialog's shape
- * @param containerColor The container color of the dialog.
- * @param tonalElevation When [containerColor] is [ColorScheme.surface], a higher tonal elevation
- * value will result in a darker dialog color in light theme and lighter color in dark theme.
- * See also [Surface].
- * @param iconContentColor The content color used for the icon.
- * @param titleContentColor The content color used for the title.
- * @param textContentColor The content color used for the text.
- * @param properties Typically platform specific properties to further configure the dialog.
+ * @param title title which should specify the purpose of the dialog. The title is not mandatory,
+ * because there may be sufficient information inside the [text].
+ * @param text text which presents the details regarding the dialog's purpose.
+ * @param shape defines the shape of this dialog's container
+ * @param containerColor the color used for the background of this dialog. Use [Color.Transparent]
+ * to have no color.
+ * @param tonalElevation when [containerColor] is [ColorScheme.surface], a translucent primary color
+ * overlay is applied on top of the container. A higher tonal elevation value will result in a
+ * darker color in light theme and lighter color in dark theme. See also: [Surface].
+ * @param iconContentColor the content color used for the icon.
+ * @param titleContentColor the content color used for the title.
+ * @param textContentColor the content color used for the text.
+ * @param properties typically platform specific properties to further configure the dialog.
  */
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable

diff --git a/compose/material3/material3/src/androidMain/kotlin/androidx/compose/material3/AndroidMenu.android.kt b/compose/material3/material3/src/androidMain/kotlin/androidx/compose/material3/AndroidMenu.android.kt
index da1fc44..3a96fdc 100644
--- a/compose/material3/material3/src/androidMain/kotlin/androidx/compose/material3/AndroidMenu.android.kt
+++ b/compose/material3/material3/src/androidMain/kotlin/androidx/compose/material3/AndroidMenu.android.kt

@@ -64,9 +64,9 @@
  * Example usage:
  * @sample androidx.compose.material3.samples.MenuSample
  *
- * @param expanded Whether the menu is currently open and visible to the user
- * @param onDismissRequest Called when the user requests to dismiss the menu, such as by
- * tapping outside the menu's bounds
+ * @param expanded whether the menu is expanded or not
+ * @param onDismissRequest called when the user requests to dismiss the menu, such as by tapping
+ * outside the menu's bounds
  * @param offset [DpOffset] to be added to the position of the menu
  */
 @Suppress("ModifierParameter")
@@ -118,21 +118,21 @@
  * Example usage:
  * @sample androidx.compose.material3.samples.MenuSample
  *
- * @param text The menu item text
- * @param onClick Called when the menu item was clicked
- * @param modifier The modifier to be applied to the menu item
- * @param leadingIcon Optional leading icon to be displayed at the beginning of the item's text
- * @param trailingIcon Optional trailing icon to be displayed at the end of the item's text. This
- * trailing icon slot can also accept [Text] to indicate a keyboard shortcut, for example.
- * @param enabled Controls the enabled state of the menu item - when `false`, the menu item
- * will not be clickable and [onClick] will not be invoked
- * @param colors [MenuItemColors] that will be used to resolve the background and content color for
- * this item in different states. See [MenuDefaults.itemColors].
+ * @param text text of the menu item
+ * @param onClick called when this menu item is clicked
+ * @param modifier the [Modifier] to be applied to this menu item
+ * @param leadingIcon optional leading icon to be displayed at the beginning of the item's text
+ * @param trailingIcon optional trailing icon to be displayed at the end of the item's text. This
+ * trailing icon slot can also accept [Text] to indicate a keyboard shortcut.
+ * @param enabled controls the enabled state of this menu item. When `false`, this component will
+ * not respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param colors [MenuItemColors] that will be used to resolve the colors used for this menu item in
+ * different states. See [MenuDefaults.itemColors].
  * @param contentPadding the padding applied to the content of this menu item
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this DropdownMenuItem. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this DropdownMenuItem in different [Interaction]s.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this menu item. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this menu item in different states.
  */
 @Composable
 fun DropdownMenuItem(

diff --git a/compose/material3/material3/src/androidMain/kotlin/androidx/compose/material3/ExposedDropdownMenu.kt b/compose/material3/material3/src/androidMain/kotlin/androidx/compose/material3/ExposedDropdownMenu.kt
index 02472dd..a79700e 100644
--- a/compose/material3/material3/src/androidMain/kotlin/androidx/compose/material3/ExposedDropdownMenu.kt
+++ b/compose/material3/material3/src/androidMain/kotlin/androidx/compose/material3/ExposedDropdownMenu.kt

@@ -84,11 +84,12 @@
  * An example of editable Exposed Dropdown Menu:
  * @sample androidx.compose.material3.samples.EditableExposedDropdownMenuSample
  *
- * @param expanded Whether the dropdown menu is expanded or not.
- * @param onExpandedChange Executes when the user clicks on the ExposedDropdownMenuBox and the
- * expansion state changes.
- * @param modifier The modifier to apply to this layout.
- * @param content The content to be displayed inside ExposedDropdownMenuBox.
+ * @param expanded whether the menu is expanded or not
+ * @param onExpandedChange called when the exposed dropdown menu is clicked and the expansion state
+ * changes.
+ * @param modifier the [Modifier] to be applied to this exposed dropdown menu
+ * @param content the content of this exposed dropdown menu, typically a [TextField] and a
+ * [ExposedDropdownMenuBoxScope.ExposedDropdownMenu]
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -203,33 +204,28 @@
 @ExperimentalMaterial3Api
 interface ExposedDropdownMenuBoxScope {
     /**
-     * Modifier which should be applied to an [ExposedDropdownMenu]
-     * placed inside the scope. It's responsible for
-     * setting the width of the [ExposedDropdownMenu], which
-     * will match the width of the [TextField]
-     * (if [matchTextFieldWidth] is set to true).
-     * Also it'll change the height of [ExposedDropdownMenu], so
-     * it'll take the largest possible height to not overlap
-     * the [TextField] and the software keyboard.
+     * Modifier which should be applied to an [ExposedDropdownMenu] placed inside the scope. It's
+     * responsible for setting the width of the [ExposedDropdownMenu], which will match the width of
+     * the [TextField] (if [matchTextFieldWidth] is set to true). It will also change the height of
+     * [ExposedDropdownMenu], so it'll take the largest possible height to not overlap the
+     * [TextField] and the software keyboard.
      *
-     * @param matchTextFieldWidth Whether menu should match
-     * the width of the text field to which it's attached.
-     * If set to true the width will match the width
-     * of the text field.
+     * @param matchTextFieldWidth whether the menu should match the width of the text field to which
+     * it's attached. If set to `true`, the width will match the width of the text field.
      */
     fun Modifier.exposedDropdownSize(
         matchTextFieldWidth: Boolean = true
     ): Modifier
 
     /**
-     * Popup which contains content for Exposed Dropdown Menu.
-     * Should be used inside the content of [ExposedDropdownMenuBox].
+     * Popup which contains content for Exposed Dropdown Menu. Should be used inside the content of
+     * [ExposedDropdownMenuBox].
      *
-     * @param expanded Whether the menu is currently open and visible to the user
-     * @param onDismissRequest Called when the user requests to dismiss the menu, such as by
+     * @param expanded whether the menu is expanded
+     * @param onDismissRequest called when the user requests to dismiss the menu, such as by
      * tapping outside the menu's bounds
-     * @param modifier The modifier to apply to this layout
-     * @param content The content of the [ExposedDropdownMenu]
+     * @param modifier the [Modifier] to be applied to this menu
+     * @param content the content of the menu
      */
     @Composable
     fun ExposedDropdownMenu(
@@ -283,9 +279,9 @@
     /**
      * Default trailing icon for Exposed Dropdown Menu.
      *
-     * @param expanded Whether [ExposedDropdownMenuBoxScope.ExposedDropdownMenu]
-     * is expanded or not. Affects the appearance of the icon.
-     * @param onIconClick Called when the icon was clicked.
+     * @param expanded whether [ExposedDropdownMenuBoxScope.ExposedDropdownMenu] is expanded or not.
+     * Affects the appearance of the icon.
+     * @param onIconClick called when the icon is clicked
      */
     @ExperimentalMaterial3Api
     @Composable
@@ -313,48 +309,33 @@
 
     /**
      * Creates a [TextFieldColors] that represents the default input text, container, and content
-     * (including label, placeholder, leading and trailing icons) colors used in a [TextField].
+     * (including label, placeholder, leading and trailing icons) colors used in a [TextField]
+     * within an [ExposedDropdownMenuBox].
      *
-     * @param textColor Represents the color used for the input text of this text field.
-     * @param disabledTextColor Represents the color used for the input text of this text field when
-     * it's disabled.
-     * @param containerColor Represents the container color for this text field.
-     * @param cursorColor Represents the cursor color for this text field.
-     * @param errorCursorColor Represents the cursor color for this text field when it's in error
-     * state.
-     * @param focusedIndicatorColor Represents the indicator color for this text field when it's
-     * focused.
-     * @param unfocusedIndicatorColor Represents the indicator color for this text field when it's
-     * not focused.
-     * @param disabledIndicatorColor Represents the indicator color for this text field when it's
-     * disabled.
-     * @param errorIndicatorColor Represents the indicator color for this text field when it's in
-     * error state.
-     * @param focusedLeadingIconColor Represents the leading icon color for this text field when
-     * it's focused.
-     * @param unfocusedLeadingIconColor Represents the leading icon color for this text field when
-     * it's not focused.
-     * @param disabledLeadingIconColor Represents the leading icon color for this text field when
-     * it's disabled.
-     * @param errorLeadingIconColor Represents the leading icon color for this text field when it's
-     * in error state.
-     * @param focusedTrailingIconColor Represents the trailing icon color for this text field when
-     * it's focused.
-     * @param unfocusedTrailingIconColor Represents the trailing icon color for this text field when
-     * it's not focused.
-     * @param disabledTrailingIconColor Represents the trailing icon color for this text field when
-     * it's disabled.
-     * @param errorTrailingIconColor Represents the trailing icon color for this text field when
-     * it's in error state.
-     * @param focusedLabelColor Represents the label color for this text field when it's focused.
-     * @param unfocusedLabelColor Represents the label color for this text field when it's not
-     * focused.
-     * @param disabledLabelColor Represents the label color for this text field when it's disabled.
-     * @param errorLabelColor Represents the label color for this text field when it's in error
-     * state.
-     * @param placeholderColor Represents the placeholder color for this text field.
-     * @param disabledPlaceholderColor Represents the placeholder color for this text field when
-     * it's disabled.
+     * @param textColor the color used for the input text of this text field
+     * @param disabledTextColor the color used for the input text of this text field when disabled
+     * @param containerColor the container color for this text field
+     * @param cursorColor the cursor color for this text field
+     * @param errorCursorColor the cursor color for this text field when in error state
+     * @param focusedIndicatorColor the indicator color for this text field when focused
+     * @param unfocusedIndicatorColor the indicator color for this text field when not focused
+     * @param disabledIndicatorColor the indicator color for this text field when disabled
+     * @param errorIndicatorColor the indicator color for this text field when in error state
+     * @param focusedLeadingIconColor the leading icon color for this text field when focused
+     * @param unfocusedLeadingIconColor the leading icon color for this text field when not focused
+     * @param disabledLeadingIconColor the leading icon color for this text field when disabled
+     * @param errorLeadingIconColor the leading icon color for this text field when in error state
+     * @param focusedTrailingIconColor the trailing icon color for this text field when focused
+     * @param unfocusedTrailingIconColor the trailing icon color for this text field when not
+     * focused
+     * @param disabledTrailingIconColor the trailing icon color for this text field when disabled
+     * @param errorTrailingIconColor the trailing icon color for this text field when in error state
+     * @param focusedLabelColor the label color for this text field when focused
+     * @param unfocusedLabelColor the label color for this text field when not focused
+     * @param disabledLabelColor the label color for this text field when disabled
+     * @param errorLabelColor the label color for this text field when in error state
+     * @param placeholderColor the placeholder color for this text field
+     * @param disabledPlaceholderColor the placeholder color for this text field when disabled
      */
     @Composable
     fun textFieldColors(
@@ -429,47 +410,31 @@
     /**
      * Creates a [TextFieldColors] that represents the default input text, container, and content
      * (including label, placeholder, leading and trailing icons) colors used in an
-     * [OutlinedTextField].
+     * [OutlinedTextField] within an [ExposedDropdownMenuBox].
      *
-     * @param textColor Represents the color used for the input text of this text field.
-     * @param disabledTextColor Represents the color used for the input text of this text field when
-     * it's disabled.
-     * @param containerColor Represents the container color for this text field.
-     * @param cursorColor Represents the cursor color for this text field.
-     * @param errorCursorColor Represents the cursor color for this text field when it's in error
-     * state.
-     * @param focusedBorderColor Represents the border color for this text field when it's focused.
-     * @param unfocusedBorderColor Represents the border color for this text field when it's not
-     * focused.
-     * @param disabledBorderColor Represents the border color for this text field when it's
-     * disabled.
-     * @param errorBorderColor Represents the border color for this text field when it's in error
-     * state.
-     * @param focusedLeadingIconColor Represents the leading icon color for this text field when
-     * it's focused.
-     * @param unfocusedLeadingIconColor Represents the leading icon color for this text field when
-     * it's not focused.
-     * @param disabledLeadingIconColor Represents the leading icon color for this text field when
-     * it's disabled.
-     * @param errorLeadingIconColor Represents the leading icon color for this text field when it's
-     * in error state.
-     * @param focusedTrailingIconColor Represents the trailing icon color for this text field when
-     * it's focused.
-     * @param unfocusedTrailingIconColor Represents the trailing icon color for this text field when
-     * it's not focused.
-     * @param disabledTrailingIconColor Represents the trailing icon color for this text field when
-     * it's disabled.
-     * @param errorTrailingIconColor Represents the trailing icon color for this text field when
-     * it's in error state.
-     * @param focusedLabelColor Represents the label color for this text field when it's focused.
-     * @param unfocusedLabelColor Represents the label color for this text field when it's not
-     * focused.
-     * @param disabledLabelColor Represents the label color for this text field when it's disabled.
-     * @param errorLabelColor Represents the label color for this text field when it's in error
-     * state.
-     * @param placeholderColor Represents the placeholder color for this text field.
-     * @param disabledPlaceholderColor Represents the placeholder color for this text field when
-     * it's disabled.
+     * @param textColor the color used for the input text of this text field
+     * @param disabledTextColor the color used for the input text of this text field when disabled
+     * @param containerColor the container color for this text field
+     * @param cursorColor the cursor color for this text field
+     * @param errorCursorColor the cursor color for this text field when in error state
+     * @param focusedBorderColor the border color for this text field when focused
+     * @param unfocusedBorderColor the border color for this text field when not focused
+     * @param disabledBorderColor the border color for this text field when disabled
+     * @param errorBorderColor the border color for this text field when in error state
+     * @param focusedLeadingIconColor the leading icon color for this text field when focused
+     * @param unfocusedLeadingIconColor the leading icon color for this text field when not focused
+     * @param disabledLeadingIconColor the leading icon color for this text field when disabled
+     * @param errorLeadingIconColor the leading icon color for this text field when in error state
+     * @param focusedTrailingIconColor the trailing icon color for this text field when focused
+     * @param unfocusedTrailingIconColor the trailing icon color for this text field when not focused
+     * @param disabledTrailingIconColor the trailing icon color for this text field when disabled
+     * @param errorTrailingIconColor the trailing icon color for this text field when in error state
+     * @param focusedLabelColor the label color for this text field when focused
+     * @param unfocusedLabelColor the label color for this text field when not focused
+     * @param disabledLabelColor the label color for this text field when disabled
+     * @param errorLabelColor the label color for this text field when in error state
+     * @param placeholderColor the placeholder color for this text field
+     * @param disabledPlaceholderColor the placeholder color for this text field when disabled
      */
     @Composable
     fun outlinedTextFieldColors(

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/AppBar.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/AppBar.kt
index 9fae7a0..fd41db4 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/AppBar.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/AppBar.kt

@@ -91,11 +91,11 @@
  *
  * @param title the title to be displayed in the top app bar
  * @param modifier the [Modifier] to be applied to this top app bar
- * @param navigationIcon The navigation icon displayed at the start of the top app bar. This should
+ * @param navigationIcon the navigation icon displayed at the start of the top app bar. This should
  * typically be an [IconButton] or [IconToggleButton].
  * @param actions the actions displayed at the end of the top app bar. This should typically be
  * [IconButton]s. The default layout here is a [Row], so icons inside will be placed horizontally.
- * @param colors a [TopAppBarColors] that will be used to resolve the colors used for this top app
+ * @param colors [TopAppBarColors] that will be used to resolve the colors used for this top app
  * bar in different states. See [TopAppBarDefaults.smallTopAppBarColors].
  * @param scrollBehavior a [TopAppBarScrollBehavior] which holds various offset values that will be
  * applied by this top app bar to set up its height and colors. A scroll behavior is designed to
@@ -140,11 +140,11 @@
  *
  * @param title the title to be displayed in the top app bar
  * @param modifier the [Modifier] to be applied to this top app bar
- * @param navigationIcon The navigation icon displayed at the start of the top app bar. This should
+ * @param navigationIcon the navigation icon displayed at the start of the top app bar. This should
  * typically be an [IconButton] or [IconToggleButton].
  * @param actions the actions displayed at the end of the top app bar. This should typically be
  * [IconButton]s. The default layout here is a [Row], so icons inside will be placed horizontally.
- * @param colors a [TopAppBarColors] that will be used to resolve the colors used for this top app
+ * @param colors [TopAppBarColors] that will be used to resolve the colors used for this top app
  * bar in different states. See [TopAppBarDefaults.centerAlignedTopAppBarColors].
  * @param scrollBehavior a [TopAppBarScrollBehavior] which holds various offset values that will be
  * applied by this top app bar to set up its height and colors. A scroll behavior is designed to
@@ -195,7 +195,7 @@
  * typically be an [IconButton] or [IconToggleButton].
  * @param actions the actions displayed at the end of the top app bar. This should typically be
  * [IconButton]s. The default layout here is a [Row], so icons inside will be placed horizontally.
- * @param colors a [TopAppBarColors] that will be used to resolve the colors used for this top app
+ * @param colors [TopAppBarColors] that will be used to resolve the colors used for this top app
  * bar in different states. See [TopAppBarDefaults.mediumTopAppBarColors].
  * @param scrollBehavior a [TopAppBarScrollBehavior] which holds various offset values that will be
  * applied by this top app bar to set up its height and colors. A scroll behavior is designed to
@@ -244,12 +244,12 @@
  * @param title the title to be displayed in the top app bar. This title will be used in the app
  * bar's expanded and collapsed states, although in its collapsed state it will be composed with a
  * smaller sized [TextStyle]
- * @param modifier The [Modifier] to be applied to this top app bar
- * @param navigationIcon The navigation icon displayed at the start of the top app bar. This should
+ * @param modifier the [Modifier] to be applied to this top app bar
+ * @param navigationIcon the navigation icon displayed at the start of the top app bar. This should
  * typically be an [IconButton] or [IconToggleButton].
- * @param actions The actions displayed at the end of the top app bar. This should typically be
+ * @param actions the actions displayed at the end of the top app bar. This should typically be
  * [IconButton]s. The default layout here is a [Row], so icons inside will be placed horizontally.
- * @param colors a [TopAppBarColors] that will be used to resolve the colors used for this top app
+ * @param colors [TopAppBarColors] that will be used to resolve the colors used for this top app
  * bar in different states. See [TopAppBarDefaults.largeTopAppBarColors].
  * @param scrollBehavior a [TopAppBarScrollBehavior] which holds various offset values that will be
  * applied by this top app bar to set up its height and colors. A scroll behavior is designed to
@@ -298,16 +298,16 @@
  *
  * @param icons the icon content of this BottomAppBar. The default layout here is a [Row],
  * so content inside will be placed horizontally.
- * @param modifier The [Modifier] to be applied to this BottomAppBar
+ * @param modifier the [Modifier] to be applied to this BottomAppBar
  * @param floatingActionButton optional floating action button at the end of this BottomAppBar
- * @param containerColor The container color for the BottomAppBar. Use [Color.Transparent] to
- * have no color.
- * @param contentColor The preferred content color provided by this BottomAppBar to its children.
- * Defaults to either the matching content color for [containerColor], or if [containerColor] is
- * not a color from the theme, this will keep the same value set above this BottomAppBar.
- * @param tonalElevation When [containerColor] is [ColorScheme.surface], a higher tonal elevation
- * value will result in a darker color in light theme and lighter color in dark theme. See also:
- * [Surface].
+ * @param containerColor the color used for the background of this BottomAppBar. Use
+ * [Color.Transparent] to have no color.
+ * @param contentColor the preferred color for content inside this BottomAppBar. Defaults to either
+ * the matching content color for [containerColor], or to the current [LocalContentColor] if
+ * [containerColor] is not a color from the theme.
+ * @param tonalElevation when [containerColor] is [ColorScheme.surface], a translucent primary color
+ * overlay is applied on top of the container. A higher tonal elevation value will result in a
+ * darker color in light theme and lighter color in dark theme. See also: [Surface].
  * @param contentPadding the padding applied to the content of this BottomAppBar
  */
 @Composable
@@ -351,13 +351,15 @@
  *
  * Also see [NavigationBar].
  *
- * @param modifier The [Modifier] to be applied to this BottomAppBar
- * @param containerColor The background color for the BottomAppBar. Use [Color.Transparent] to
- * have no color.
- * @param contentColor The preferred content color provided by this BottomAppBar to its children.
- * Defaults to either the matching content color for [containerColor], or if [containerColor] is
- * not a color from the theme, this will keep the same value set above this BottomAppBar.
- * @param tonalElevation the elevation of this BottomAppBar.
+ * @param modifier the [Modifier] to be applied to this BottomAppBar
+ * @param containerColor the color used for the background of this BottomAppBar. Use
+ * [Color.Transparent] to have no color.
+ * @param contentColor the preferred color for content inside this BottomAppBar. Defaults to either
+ * the matching content color for [containerColor], or to the current [LocalContentColor] if
+ * [containerColor] is not a color from the theme.
+ * @param tonalElevation when [containerColor] is [ColorScheme.surface], a translucent primary color
+ * overlay is applied on top of the container. A higher tonal elevation value will result in a
+ * darker color in light theme and lighter color in dark theme. See also: [Surface].
  * @param contentPadding the padding applied to the content of this BottomAppBar
  * @param content the content of this BottomAppBar. The default layout here is a [Row],
  * so content inside will be placed horizontally.
@@ -412,9 +414,8 @@
      *
      * A scrollFraction is a value between `0.0` to `1.0` that provides a percentage of the app
      * bar scroll position when the content is scrolled. `0.0` represents an expanded app bar,
-     * while `1.0`
-     * represents a collapsed one (e.g. the app bar is scrolled to its target offset). Note that
-     * this value will be updated on scroll even if the [offset] is pinned to a specific
+     * while `1.0` represents a collapsed one (e.g. the app bar is scrolled to its target offset).
+     * Note that this value will be updated on scroll even if the [offset] is pinned to a specific
      * value (see [TopAppBarDefaults.pinnedScrollBehavior]). In this case a value of 1.0 represents
      * that the scroll value has exceeded the height of the pinned app bar, as if the app bar was
      * collapsing.

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Badge.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Badge.kt
index 62f29e1..3fde459 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Badge.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Badge.kt

@@ -53,7 +53,7 @@
  * @sample androidx.compose.material3.samples.NavigationBarItemWithBadge
  *
  * @param badge the badge to be displayed - typically a [Badge]
- * @param modifier optional [Modifier] for this item
+ * @param modifier the [Modifier] to be applied to this BadgedBox
  * @param content the anchor to which this badge will be positioned
  *
  */
@@ -121,16 +121,18 @@
  * A badge represents dynamic information such as a number of pending requests in a navigation bar.
  *
  * Badges can be icon only or contain short text.
-
+ *
  * ![Badge image](https://developer.android.com/images/reference/androidx/compose/material3/badge.png)
  *
  * See [BadgedBox] for a top level layout that will properly place the badge relative to content
  * such as text or an icon.
  *
- * @param modifier optional [Modifier] for this item
- * @param containerColor the background color for the badge
- * @param contentColor the color of label text rendered in the badge
- * @param content optional content to be rendered inside the badge
+ * @param modifier the [Modifier] to be applied to this badge
+ * @param containerColor the color used for the background of this badge
+ * @param contentColor the preferred color for content inside this badge. Defaults to either the
+ * matching content color for [containerColor], or to the current [LocalContentColor] if
+ * [containerColor] is not a color from the theme.
+ * @param content optional content to be rendered inside this badge
  */
 @Composable
 fun Badge(

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Button.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Button.kt
index bb72576..17f98e6 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Button.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Button.kt

@@ -79,24 +79,25 @@
  *
  * The default text style for internal [Text] components will be set to [Typography.labelLarge].
  *
- * @param onClick Will be called when the user clicks the button.
- * @param modifier Modifier to be applied to the button.
- * @param enabled Controls the enabled state of the button. When `false`, this button will not be
- * clickable.
+ * @param onClick called when this button is clicked
+ * @param modifier the [Modifier] to be applied to this button
+ * @param enabled controls the enabled state of this button. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
  * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
- * for this Button. You can create and pass in your own remembered [MutableInteractionSource] if you
- * want to observe [Interaction]s and customize the appearance / behavior of this Button in
- * different [Interaction]s.
+ * for this button. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this button in different states.
  * @param elevation [ButtonElevation] used to resolve the elevation for this button in different
- * states. This controls the size of the shadow below the button. When the container color is
- * [ColorScheme.surface], a higher elevation (surface blended with more primary) will result in a
- * darker surface color in light theme and lighter color in dark theme.
- * @param shape Defines the button's shape as well as its shadow.
- * @param border Border to draw around the button. Pass `null` here for no border.
- * @param colors [ButtonColors] that will be used to resolve the container and content color for
- * this button in different states. See [ButtonDefaults.buttonColors].
- * @param contentPadding The spacing values to apply internally between the container and the
- * content.
+ * states. This controls the size of the shadow below the button. Additionally, when the container
+ * color is [ColorScheme.surface], this controls the amount of primary color applied as an overlay.
+ * See [ButtonElevation.shadowElevation] and [ButtonElevation.tonalElevation].
+ * @param shape defines the shape of this button's container, border (when [border] is not null),
+ * and shadow (when using [elevation])
+ * @param border the border to draw around the container of this button
+ * @param colors [ButtonColors] that will be used to resolve the colors for this button in different
+ * states. See [ButtonDefaults.buttonColors].
+ * @param contentPadding the spacing values to apply internally between the container and the
+ * content
  */
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
@@ -171,25 +172,25 @@
  *
  * The default text style for internal [Text] components will be set to [Typography.labelLarge].
  *
- * @param onClick Will be called when the user clicks the button.
- * @param modifier Modifier to be applied to the button.
- * @param enabled Controls the enabled state of the button. When `false`, this button will not be
- * clickable.
+ * @param onClick called when this button is clicked
+ * @param modifier the [Modifier] to be applied to this button
+ * @param enabled controls the enabled state of this button. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
  * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
- * for this Button. You can create and pass in your own remembered [MutableInteractionSource] if you
- * want to observe [Interaction]s and customize the appearance / behavior of this Button in
- * different [Interaction]s.
+ * for this button. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this button in different states.
  * @param elevation [ButtonElevation] used to resolve the elevation for this button in different
- * states. This controls the size of the shadow below the button. When the container color is
- * [ColorScheme.surface], a higher elevation (surface blended with more primary) will result in a
- * darker surface color in light theme and lighter color in dark theme.
- * [ButtonDefaults.elevatedButtonElevation].
- * @param shape Defines the button's shape as well as its shadow.
- * @param border Border to draw around the button. Pass `null` here for no border.
- * @param colors [ButtonColors] that will be used to resolve the container and content color for
- * this button in different states. See [ButtonDefaults.elevatedButtonColors].
- * @param contentPadding The spacing values to apply internally between the container and the
- * content.
+ * states. This controls the size of the shadow below the button. Additionally, when the container
+ * color is [ColorScheme.surface], this controls the amount of primary color applied as an overlay.
+ * See [ButtonDefaults.elevatedButtonElevation].
+ * @param shape defines the shape of this button's container, border (when [border] is not null),
+ * and shadow (when using [elevation])
+ * @param border the border to draw around the container of this button
+ * @param colors [ButtonColors] that will be used to resolve the colors for this button in different
+ * states. See [ButtonDefaults.elevatedButtonColors].
+ * @param contentPadding the spacing values to apply internally between the container and the
+ * content
  */
 @Composable
 fun ElevatedButton(
@@ -242,24 +243,24 @@
  *
  * The default text style for internal [Text] components will be set to [Typography.labelLarge].
  *
- * @param onClick Will be called when the user clicks the button.
- * @param modifier Modifier to be applied to the button.
- * @param enabled Controls the enabled state of the button. When `false`, this button will not be
- * clickable.
+ * @param onClick called when this button is clicked
+ * @param modifier the [Modifier] to be applied to this button
+ * @param enabled controls the enabled state of this button. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
  * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
- * for this Button. You can create and pass in your own remembered [MutableInteractionSource] if you
- * want to observe [Interaction]s and customize the appearance / behavior of this Button in
- * different [Interaction]s.
+ * for this button. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this button in different states.
  * @param elevation [ButtonElevation] used to resolve the elevation for this button in different
- * states. This controls the size of the shadow below the button. When the container color is
- * [ColorScheme.surface], a higher elevation (surface blended with more primary) will result in a
- * darker surface color in light theme and lighter color in dark theme.
- * @param shape Defines the button's shape as well as its shadow.
- * @param border Border to draw around the button. Pass `null` here for no border.
- * @param colors [ButtonColors] that will be used to resolve the container and content color for
- * this button in different states. See [ButtonDefaults.elevatedButtonColors].
- * @param contentPadding The spacing values to apply internally between the container and the
- * content.
+ * states. This controls the size of the shadow below the button. Additionally, when the container
+ * color is [ColorScheme.surface], this controls the amount of primary color applied as an overlay.
+ * @param shape defines the shape of this button's container, border (when [border] is not null),
+ * and shadow (when using [elevation])
+ * @param border the border to draw around the container of this button
+ * @param colors [ButtonColors] that will be used to resolve the colors for this button in different
+ * states. See [ButtonDefaults.filledTonalButtonColors].
+ * @param contentPadding the spacing values to apply internally between the container and the
+ * content
  */
 @Composable
 fun FilledTonalButton(
@@ -311,24 +312,24 @@
  *
  * The default text style for internal [Text] components will be set to [Typography.labelLarge].
  *
- * @param onClick Will be called when the user clicks the button.
- * @param modifier Modifier to be applied to the button.
- * @param enabled Controls the enabled state of the button. When `false`, this button will not be
- * clickable.
+ * @param onClick called when this button is clicked
+ * @param modifier the [Modifier] to be applied to this button
+ * @param enabled controls the enabled state of this button. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
  * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
- * for this Button. You can create and pass in your own remembered [MutableInteractionSource] if you
- * want to observe [Interaction]s and customize the appearance / behavior of this Button in
- * different [Interaction]s.
+ * for this button. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this button in different states.
  * @param elevation [ButtonElevation] used to resolve the elevation for this button in different
- * states. This controls the size of the shadow below the button. When the container color is
- * [ColorScheme.surface], a higher elevation (surface blended with more primary) will result in a
- * darker surface color in light theme and lighter color in dark theme.
- * @param shape Defines the button's shape as well as its shadow.
- * @param border Border to draw around the button. Pass `null` here for no border.
- * @param colors [ButtonColors] that will be used to resolve the container and content color for
- * this button in different states. See [ButtonDefaults.elevatedButtonColors].
- * @param contentPadding The spacing values to apply internally between the container and the
- * content.
+ * states. This controls the size of the shadow below the button. Additionally, when the container
+ * color is [ColorScheme.surface], this controls the amount of primary color applied as an overlay.
+ * @param shape defines the shape of this button's container, border (when [border] is not null),
+ * and shadow (when using [elevation]).
+ * @param border the border to draw around the container of this button. Pass `null` for no border.
+ * @param colors [ButtonColors] that will be used to resolve the colors for this button in different
+ * states. See [ButtonDefaults.outlinedButtonColors].
+ * @param contentPadding the spacing values to apply internally between the container and the
+ * content
  */
 @Composable
 fun OutlinedButton(
@@ -380,27 +381,26 @@
  *
  * The default text style for internal [Text] components will be set to [Typography.labelLarge].
  *
- * @param onClick Will be called when the user clicks the button.
- * @param modifier Modifier to be applied to the button.
- * @param enabled Controls the enabled state of the button. When `false`, this button will not be
- * clickable.
+ * @param onClick called when this button is clicked
+ * @param modifier the [Modifier] to be applied to this button
+ * @param enabled controls the enabled state of this button. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
  * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
- * for this Button. You can create and pass in your own remembered [MutableInteractionSource] if you
- * want to observe [Interaction]s and customize the appearance / behavior of this Button in
- * different [Interaction]s.
+ * for this button. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this button in different states.
  * @param elevation [ButtonElevation] used to resolve the elevation for this button in different
- * states. This controls the size of the shadow below the button. When the container color is
- * [ColorScheme.surface], a higher elevation (surface blended with more primary) will result in a
- * darker surface color in light theme and lighter color in dark theme. A TextButton typically has
- * no elevation, and the default value is `null`. See [ElevatedButton] for a button with elevation.
- * @param shape Defines the button's shape. A TextButton typically has no elevation or shadow, but
- * if a non-zero or non-null elevation is passed in, then the shape also defines the bounds of the
- * shadow.
- * @param border Border to draw around the button.
- * @param colors [ButtonColors] that will be used to resolve the container and content color for
- * this button in different states. See [ButtonDefaults.textButtonColors].
- * @param contentPadding The spacing values to apply internally between the container and the
- * content.
+ * states. This controls the size of the shadow below the button. Additionally, when the container
+ * color is [ColorScheme.surface], this controls the amount of primary color applied as an overlay.
+ * A TextButton typically has no elevation, and the default value is `null`. See [ElevatedButton]
+ * for a button with elevation.
+ * @param shape defines the shape of this button's container, border (when [border] is not null),
+ * and shadow (when using [elevation])
+ * @param border the border to draw around the container of this button
+ * @param colors [ButtonColors] that will be used to resolve the colors for this button in different
+ * states. See [ButtonDefaults.textButtonColors].
+ * @param contentPadding the spacing values to apply internally between the container and the
+ * content
  */
 @Composable
 fun TextButton(
@@ -764,34 +764,32 @@
 @Stable
 interface ButtonElevation {
     /**
-     * Represents the tonal elevation used in a button, depending on [enabled] and
+     * Represents the tonal elevation used in a button, depending on its [enabled] state and
      * [interactionSource]. This should typically be the same value as the [shadowElevation].
      *
      * Tonal elevation is used to apply a color shift to the surface to give the it higher emphasis.
-     * When surface's color is [ColorScheme.surface], a higher the elevation will result
-     * in a darker color in light theme and lighter color in dark theme.
+     * When surface's color is [ColorScheme.surface], a higher elevation will result in a darker
+     * color in light theme and lighter color in dark theme.
      *
-     * See [shadowElevation] which controls the elevation of the shadow drawn around the FAB.
+     * See [shadowElevation] which controls the elevation of the shadow drawn around the button.
      *
      * @param enabled whether the button is enabled
      * @param interactionSource the [InteractionSource] for this button
      */
-    // TODO(b/202954622): Align docs with [FloatingActionButtonElevation].
     @Composable
     fun tonalElevation(enabled: Boolean, interactionSource: InteractionSource): State<Dp>
 
     /**
-     * Represents the shadow elevation used in a button, depending on [enabled] and
+     * Represents the shadow elevation used in a button, depending on its [enabled] state and
      * [interactionSource]. This should typically be the same value as the [tonalElevation].
      *
-     * Shadow elevation is used to apply a shadow around the surface to give it higher emphasis.
+     * Shadow elevation is used to apply a shadow around the button to give it higher emphasis.
      *
      * See [tonalElevation] which controls the elevation with a color shift to the surface.
      *
      * @param enabled whether the button is enabled
      * @param interactionSource the [InteractionSource] for this button
      */
-    // TODO(b/202954622): Align docs with [FloatingActionButtonElevation].
     @Composable
     fun shadowElevation(enabled: Boolean, interactionSource: InteractionSource): State<Dp>
 }

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Card.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Card.kt
index 7da6db4..6e640bf 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Card.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Card.kt

@@ -63,15 +63,16 @@
  * Card sample:
  * @sample androidx.compose.material3.samples.CardSample
  *
- * @param modifier Modifier to be applied to the layout of the card.
- * @param shape Defines the card's shape.
- * @param border [BorderStroke] to draw on top of the card.
- * @param elevation [CardElevation] used to resolve the elevation for this card. The resolved value
- * control the size of the shadow below the card, as well as its tonal elevation. When the container
- * color is [ColorScheme.surface], a higher tonal elevation value will result in a darker
- * card color in light theme and lighter color in dark theme. See also [Surface].
- * @param colors [CardColors] that will be used to resolve the container and content color for
- * this card. See [CardDefaults.cardColors].
+ * @param modifier the [Modifier] to be applied to this card
+ * @param shape defines the shape of this card's container, border (when [border] is not null), and
+ * shadow (when using [elevation])
+ * @param border the border to draw around the container of this card
+ * @param elevation [CardElevation] used to resolve the elevation for this card in different states.
+ * This controls the size of the shadow below the card. Additionally, when the container color is
+ * [ColorScheme.surface], this controls the amount of primary color applied as an overlay. See also:
+ * [Surface].
+ * @param colors [CardColors] that will be used to resolve the colors used for this card in
+ * different states. See [CardDefaults.cardColors].
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -110,23 +111,23 @@
  * Clickable card sample:
  * @sample androidx.compose.material3.samples.ClickableCardSample
  *
- * @param onClick Callback to be called when the card is clicked
- * @param modifier Modifier to be applied to the layout of the card.
- * @param enabled Controls the enabled state of the card. When `false`, this card will not
- * be clickable and the card will resolve its [elevation] and [colors] accordingly.
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this Card. You can create and pass in your own remembered
- * [MutableInteractionSource] to observe [Interaction]s that will customize the appearance
- * / behavior of this card in different states.
- * @param shape Defines the card's shape.
- * @param border [BorderStroke] to draw on top of the card.
- * @param elevation [CardElevation] used to resolve the elevation for this card when the
- * [interactionSource] emits its states. The resolved values control the size of the shadow below
- * the card, as well as its tonal elevation. When the container color is [ColorScheme.surface], a
- * higher tonal elevation value will result in a darker card color in light theme and lighter color
- * in dark theme. See also [Surface].
- * @param colors [CardColors] that will be used to resolve the container and content color for
- * this card in different states. See [CardDefaults.cardColors].
+ * @param onClick called when this card is clicked
+ * @param modifier the [Modifier] to be applied to this card
+ * @param enabled controls the enabled state of this card. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this card. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this card in different states.
+ * @param shape defines the shape of this card's container, border (when [border] is not null), and
+ * shadow (when using [elevation])
+ * @param border the border to draw around the container of this card
+ * @param elevation [CardElevation] used to resolve the elevation for this card in different states.
+ * This controls the size of the shadow below the card. Additionally, when the container color is
+ * [ColorScheme.surface], this controls the amount of primary color applied as an overlay. See also:
+ * [Surface].
+ * @param colors [CardColors] that will be used to resolve the color(s) used for this card in
+ * different states. See [CardDefaults.cardColors].
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -172,14 +173,14 @@
  * Elevated card sample:
  * @sample androidx.compose.material3.samples.ElevatedCardSample
  *
- * @param modifier Modifier to be applied to the layout of the card.
- * @param shape Defines the card's shape.
- * @param elevation [CardElevation] used to resolve the elevation for this card. The resolved value
- * control the size of the shadow below the card, as well as its tonal elevation. When the container
- * color is [ColorScheme.surface], a higher tonal elevation value will result in a darker
- * card color in light theme and lighter color in dark theme. See also [Surface].
- * @param colors [CardColors] that will be used to resolve the container and content color for
- * this card. See [CardDefaults.elevatedCardElevation].
+ * @param modifier the [Modifier] to be applied to this card
+ * @param shape defines the shape of this card's container and shadow (when using [elevation])
+ * @param elevation [CardElevation] used to resolve the elevation for this card in different states.
+ * This controls the size of the shadow below the card. Additionally, when the container color is
+ * [ColorScheme.surface], this controls the amount of primary color applied as an overlay. See also:
+ * [Surface].
+ * @param colors [CardColors] that will be used to resolve the color(s) used for this card in
+ * different states. See [CardDefaults.elevatedCardElevation].
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -212,22 +213,21 @@
  * Clickable elevated card sample:
  * @sample androidx.compose.material3.samples.ClickableElevatedCardSample
  *
- * @param onClick Callback to be called when the card is clicked
- * @param modifier Modifier to be applied to the layout of the card.
- * @param enabled Controls the enabled state of the card. When `false`, this card will not
- * be clickable and the card will resolve its [elevation] and [colors] accordingly.
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this card. You can create and pass in your own remembered
- * [MutableInteractionSource] to observe [Interaction]s that will customize the appearance
- * / behavior of this card in different states.
- * @param shape Defines the card's shape.
- * @param elevation [CardElevation] used to resolve the elevation for this card when the
- * [interactionSource] emits its states. The resolved values control the size of the shadow below
- * the card, as well as its tonal elevation. When the container color is [ColorScheme.surface], a
- * higher tonal elevation value will result in a darker card color in light theme and lighter color
- * in dark theme. See also [Surface].
- * @param colors [CardColors] that will be used to resolve the container and content color for
- * this card. See [CardDefaults.elevatedCardColors].
+ * @param onClick called when this card is clicked
+ * @param modifier the [Modifier] to be applied to this card
+ * @param enabled controls the enabled state of this card. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this card. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this card in different states.
+ * @param shape defines the shape of this card's container and shadow (when using [elevation])
+ * @param elevation [CardElevation] used to resolve the elevation for this card in different states.
+ * This controls the size of the shadow below the card. Additionally, when the container color is
+ * [ColorScheme.surface], this controls the amount of primary color applied as an overlay. See also:
+ * [Surface].
+ * @param colors [CardColors] that will be used to resolve the color(s) used for this card in
+ * different states. See [CardDefaults.elevatedCardElevation].
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -266,15 +266,16 @@
  * Outlined card sample:
  * @sample androidx.compose.material3.samples.OutlinedCardSample
  *
- * @param modifier Modifier to be applied to the layout of the card.
- * @param shape Defines the card's shape.
- * @param border [BorderStroke] to draw on top of the card.
- * @param elevation [CardElevation] used to resolve the elevation for this card. The resolved value
- * control the size of the shadow below the card, as well as its tonal elevation. When the container
- * color is [ColorScheme.surface], a higher tonal elevation value will result in a darker
- * card color in light theme and lighter color in dark theme. See also [Surface].
- * @param colors [CardColors] that will be used to resolve the container and content color for
- * this card. See [CardDefaults.outlinedCardColors].
+ * @param modifier the [Modifier] to be applied to this card
+ * @param shape defines the shape of this card's container, border (when [border] is not null), and
+ * shadow (when using [elevation])
+ * @param border the border to draw around the container of this card
+ * @param elevation [CardElevation] used to resolve the elevation for this card in different states.
+ * This controls the size of the shadow below the card. Additionally, when the container color is
+ * [ColorScheme.surface], this controls the amount of primary color applied as an overlay. See also:
+ * [Surface].
+ * @param colors [CardColors] that will be used to resolve the color(s) used for this card in
+ * different states. See [CardDefaults.outlinedCardColors].
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -307,23 +308,23 @@
  * Clickable outlined card sample:
  * @sample androidx.compose.material3.samples.ClickableOutlinedCardSample
  *
- * @param onClick Callback to be called when the card is clicked
- * @param modifier Modifier to be applied to the layout of the card.
- * @param enabled Controls the enabled state of the card. When `false`, this card will not
- * be clickable and the card will resolve its [elevation] and [colors] accordingly.
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this card. You can create and pass in your own remembered
- * [MutableInteractionSource] to observe [Interaction]s that will customize the appearance
- * / behavior of this card in different states.
- * @param shape Defines the card's shape.
- * @param border [BorderStroke] to draw on top of the card.
- * @param elevation [CardElevation] used to resolve the elevation for this card when the
- * [interactionSource] emits its states. The resolved values control the size of the shadow below
- * the card, as well as its tonal elevation. When the container is [ColorScheme.surface], a
- * higher tonal elevation value will result in a darker card color in light theme and lighter color
- * in dark theme. See also [Surface].
- * @param colors [CardColors] that will be used to resolve the container and content color for
- * this card in different states. See [CardDefaults.outlinedCardColors].
+ * @param onClick called when this card is clicked
+ * @param modifier the [Modifier] to be applied to this card
+ * @param enabled controls the enabled state of this card. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this card. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this card in different states.
+ * @param shape defines the shape of this card's container, border (when [border] is not null), and
+ * shadow (when using [elevation])
+ * @param border the border to draw around the container of this card
+ * @param elevation [CardElevation] used to resolve the elevation for this card in different states.
+ * This controls the size of the shadow below the card. Additionally, when the container color is
+ * [ColorScheme.surface], this controls the amount of primary color applied as an overlay. See also:
+ * [Surface].
+ * @param colors [CardColors] that will be used to resolve the color(s) used for this card in
+ * different states. See [CardDefaults.outlinedCardColors].
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -360,13 +361,13 @@
 interface CardElevation {
     /**
      * Represents the tonal elevation used in a card, depending on its [enabled] state and
-     * [interactionSource].
+     * [interactionSource]. This should typically be the same value as the [shadowElevation].
      *
      * Tonal elevation is used to apply a color shift to the surface to give the it higher emphasis.
+     * When surface's color is [ColorScheme.surface], a higher elevation will result in a darker
+     * color in light theme and lighter color in dark theme.
      *
-     * For all Material cards with elevation, this returns the same value as [shadowElevation].
-     *
-     * - See [shadowElevation] for an elevation that draws a shadow around the card's bounds.
+     * See [shadowElevation] which controls the elevation of the shadow drawn around the card.
      *
      * @param enabled whether the card is enabled
      * @param interactionSource the [InteractionSource] for this card
@@ -375,14 +376,12 @@
     fun tonalElevation(enabled: Boolean, interactionSource: InteractionSource?): State<Dp>
 
     /**
-     * Represents the shadow elevation used in a card, depending on on its [enabled] state and
-     * [interactionSource].
+     * Represents the shadow elevation used in a card, depending on its [enabled] state and
+     * [interactionSource]. This should typically be the same value as the [tonalElevation].
      *
-     * Shadow elevation is used to apply a drop shadow around the card to give it higher emphasis.
+     * Shadow elevation is used to apply a shadow around the card to give it higher emphasis.
      *
-     * For all Material cards with elevation, this returns the same value as [tonalElevation].
-     *
-     * - See [tonalElevation] for an elevation that applies a color shift to the surface.
+     * See [tonalElevation] which controls the elevation with a color shift to the surface.
      *
      * @param enabled whether the card is enabled
      * @param interactionSource the [InteractionSource] for this card

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Checkbox.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Checkbox.kt
index 28a6d67..7e20a60 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Checkbox.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Checkbox.kt

@@ -68,19 +68,18 @@
  *
  * @see [TriStateCheckbox] if you require support for an indeterminate state.
  *
- * @param checked whether this Checkbox is checked or unchecked
- * @param onCheckedChange callback to be invoked when checkbox is being clicked,
- * therefore the change of checked state in requested.  If null, then this is passive
- * and relies entirely on a higher-level component to control the "checked" state
- * @param modifier Modifier to be applied to the layout of this [Checkbox]
- * @param enabled controls the enabled state of the [Checkbox]. When `false`, this [Checkbox] will
- * not be clickable/selectable
+ * @param checked whether this checkbox is checked or unchecked
+ * @param onCheckedChange called when this checkbox is clicked. If `null`, then this checkbox will
+ * not be interactable, unless something else handles its input events and updates its state.
+ * @param modifier the [Modifier] to be applied to this checkbox
+ * @param enabled controls the enabled state of this checkbox. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
  * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
- * for this [Checkbox]. You can create and pass in your own remembered [MutableInteractionSource] if
- * you want to observe [Interaction]s and customize the appearance / behavior of this [Checkbox] in
- * different [Interaction]s
- * @param colors [CheckboxColors] that will be used to resolve the color used for this [Checkbox] in
- * different states. See [CheckboxDefaults.colors]
+ * for this checkbox. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this checkbox in different states.
+ * @param colors [CheckboxColors] that will be used to resolve the colors used for this checkbox in
+ * different states. See [CheckboxDefaults.colors].
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -118,21 +117,18 @@
  *
  * @see [Checkbox] if you want a simple component that represents Boolean state
  *
- * @param state whether TriStateCheckbox is checked, unchecked or in indeterminate state
- * callback to be invoked when the TriStateCheckbox is clicked.
-
- * @param onClick callback to be invoked when checkbox is being clicked, therefore the change of
- * ToggleableState state is requested. If null, then this [TriStateCheckbox] will not handle input
- * events, and only act as a visual indicator of [state]
- * @param modifier Modifier to be applied to the layout of the [TriStateCheckbox]
- * @param enabled controls the enabled state of the [TriStateCheckbox]. When `false`, this
- * [TriStateCheckbox] will not be clickable/selectable
+ * @param state whether this checkbox is checked, unchecked, or in an indeterminate state
+ * @param onClick called when this checkbox is clicked. If `null`, then this checkbox will not be
+ * interactable, unless something else handles its input events and updates its [state].
+ * @param modifier the [Modifier] to be applied to this checkbox
+ * @param enabled controls the enabled state of this checkbox. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
  * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
- * for this [TriStateCheckbox]. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this [TriStateCheckbox] in different [Interaction]s
- * @param colors [CheckboxColors] that will be used to resolve the color used for this
- * [TriStateCheckbox] in different states. See [CheckboxDefaults.colors]
+ * for this checkbox. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this checkbox in different states.
+ * @param colors [CheckboxColors] that will be used to resolve the colors used for this checkbox in
+ * different states. See [CheckboxDefaults.colors].
  */
 @Composable
 fun TriStateCheckbox(

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Chip.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Chip.kt
index d7784eb..ab9214a 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Chip.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Chip.kt

@@ -79,29 +79,28 @@
  * Example of a flat AssistChip:
  * @sample androidx.compose.material3.samples.AssistChipSample
  *
- * @param onClick Called when the chip is clicked. If null, then this chip will be considered
- * read-only unless something else handles its input events and updates its state.
- * @param label A text label for this chip
- * @param modifier Modifier to be applied to the chip
- * @param enabled When disabled, chip will not respond to user input. It will also appear visually
- * disabled and disabled to accessibility services.
- * @param leadingIcon Optional icon at the start of the chip, preceding the [label] text.
- * @param trailingIcon Optional icon at the end of the chip.
- * @param interactionSource The [MutableInteractionSource] represents the stream of [Interaction]s
- * for this chip. You can create and pass in your own remembered [MutableInteractionSource] if you
- * want to observe [Interaction]s and customize the appearance / behavior of this chip in
- * different [Interaction]s
- * @param elevation [ChipElevation] used to resolve the elevation for this chip. The resolved value
- * controls the size of the shadow below the chip, as well as its tonal elevation. When
- * chip's container color is [ColorScheme.surface], a higher tonal elevation value will result in a
- * darker chip color in light theme and lighter color in dark theme. See also [Surface] and
+ * @param onClick called when this chip is clicked. If `null`, then this chip will not be
+ * interactable, unless something else handles its input events and updates its state.
+ * @param label text label for this chip
+ * @param modifier the [Modifier] to be applied to this chip
+ * @param enabled controls the enabled state of this chip. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param leadingIcon optional icon at the start of the chip, preceding the [label] text
+ * @param trailingIcon optional icon at the end of the chip
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this chip. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this chip in different states.
+ * @param elevation [ChipElevation] used to resolve the elevation for this chip in different states.
+ * This controls the size of the shadow below the chip. Additionally, when the container color is
+ * [ColorScheme.surface], this controls the amount of primary color applied as an overlay. See
  * [AssistChipDefaults.assistChipElevation].
- * @param shape Defines the chip's shape as well its shadow. A shadow is only displayed if the
- * [elevation] is resolved to be greater than zero.
- * @param border [ChipBorder] that will be used to resolve the border to draw around the chip. Pass
- * `null` here for no border. See [AssistChipDefaults.assistChipBorder].
- * @param colors [ChipColors] that will be used to resolve the container and content color for this
- * chip in different states. See [AssistChipDefaults.assistChipColors].
+ * @param shape defines the shape of this chip's container, border (when [border] is not null), and
+ * shadow (when using [elevation])
+ * @param border the border to draw around the container of this chip. Pass `null` for no border.
+ * See [AssistChipDefaults.assistChipBorder].
+ * @param colors [ChipColors] that will be used to resolve the colors used for this chip in
+ * different states. See [AssistChipDefaults.assistChipColors].
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -158,29 +157,27 @@
  * Example of an elevated AssistChip with a trailing icon:
  * @sample androidx.compose.material3.samples.ElevatedAssistChipSample
  *
- * @param onClick Called when the chip is clicked. If null, then this chip will be considered
- * read-only unless something else handles its input events and updates its state.
- * @param label A text label for this chip
- * @param modifier Modifier to be applied to the chip
- * @param enabled When disabled, chip will not respond to user input. It will also appear visually
- * disabled and disabled to accessibility services.
- * @param leadingIcon Optional icon at the start of the chip, preceding the [label] text.
- * @param trailingIcon Optional icon at the end of the chip.
- * @param interactionSource The [MutableInteractionSource] represents the stream of [Interaction]s
- * for this chip. You can create and pass in your own remembered [MutableInteractionSource] if you
- * want to observe [Interaction]s and customize the appearance / behavior of this chip in
- * different [Interaction]s
- * @param elevation [ChipElevation] used to resolve the elevation for this chip. The resolved value
- * controls the size of the shadow below the chip, as well as its tonal elevation. When
- * chip's container color is [ColorScheme.surface], a higher tonal elevation value will result in a
- * darker chip color in light theme and lighter color in dark theme. See also [Surface] and
+ * @param onClick called when this chip is clicked. If `null`, then this chip will not be
+ * interactable, unless something else handles its input events and updates its state.
+ * @param label text label for this chip
+ * @param modifier the [Modifier] to be applied to this chip
+ * @param enabled controls the enabled state of this chip. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param leadingIcon optional icon at the start of the chip, preceding the [label] text
+ * @param trailingIcon optional icon at the end of the chip
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this chip. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this chip in different states.
+ * @param elevation [ChipElevation] used to resolve the elevation for this chip in different states.
+ * This controls the size of the shadow below the chip. Additionally, when the container color is
+ * [ColorScheme.surface], this controls the amount of primary color applied as an overlay. See
  * [AssistChipDefaults.elevatedAssistChipElevation].
- * @param shape Defines the chip's shape as well its shadow. A shadow is only displayed if the
- * [elevation] is resolved to be greater than zero.
- * @param border [ChipBorder] that will be used to resolve the border to draw around the chip. Pass
- * `null` here for no border.
- * @param colors [ChipColors] that will be used to resolve the container and content color for this
- * chip in different states. See [AssistChipDefaults.elevatedAssistChipColors].
+ * @param shape defines the shape of this chip's container, border (when [border] is not null), and
+ * shadow (when using [elevation])
+ * @param border the border to draw around the container of this chip
+ * @param colors [ChipColors] that will be used to resolve the colors used for this chip in
+ * different states. See [AssistChipDefaults.elevatedAssistChipColors].
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -242,32 +239,31 @@
  * Example of a FilterChip with both a leading icon and a selected icon:
  * @sample androidx.compose.material3.samples.FilterChipWithLeadingIconSample
  *
- * @param selected Whether the chip is selected
- * @param onClick Called when the chip is clicked. If null, then this chip will be considered
- * read-only unless something else handles its input events and updates its state.
- * @param label A text label for this chip
- * @param modifier Modifier to be applied to the chip
- * @param enabled When disabled, chip will not respond to user input. It will also appear visually
- * disabled and disabled to accessibility services.
- * @param leadingIcon Optional icon at the start of the chip, preceding the [label] text.
- * @param selectedIcon Optional icon at the start of the chip, preceding the [label] text, that will
- * de displayed when the chip is selected, instead of any given [leadingIcon].
- * @param trailingIcon Optional icon at the end of the chip.
- * @param interactionSource The [MutableInteractionSource] represents the stream of [Interaction]s
- * for this chip. You can create and pass in your own remembered [MutableInteractionSource] if you
- * want to observe [Interaction]s and customize the appearance / behavior of this chip in
- * different [Interaction]s
- * @param elevation [SelectableChipElevation] used to resolve the elevation for this chip. The
- * resolved value controls the size of the shadow below the chip, as well as its tonal elevation.
- * When chip's container color is [ColorScheme.surface], a higher tonal elevation value will result
- * in a darker chip color in light theme and lighter color in dark theme. See also [Surface] and
- * [FilterChipDefaults.filterChipElevation].
- * @param shape Defines the chip's shape as well its shadow. A shadow is only displayed if the
- * [elevation] is resolved to be greater than zero.
- * @param border [SelectableChipBorder] that will be used to resolve the border to draw around the
- * chip. Pass `null` here for no border. See [FilterChipDefaults.filterChipBorder].
- * @param colors [SelectableChipColors] that will be used to resolve the container and content color
- * for this chip in different states. See [FilterChipDefaults.filterChipColors].
+ * @param selected whether this chip is selected or not
+ * @param onClick called when this chip is clicked. If `null`, then this chip will not be
+ * interactable, unless something else handles its input events and updates its state.
+ * @param label text label for this chip
+ * @param modifier the [Modifier] to be applied to this chip
+ * @param enabled controls the enabled state of this chip. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param leadingIcon optional icon at the start of the chip, preceding the [label] text
+ * @param selectedIcon optional icon at the start of the chip, preceding the [label] text, which is
+ * displayed when the chip is selected, instead of any given [leadingIcon]
+ * @param trailingIcon optional icon at the end of the chip
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this chip. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this chip in different states.
+ * @param elevation [SelectableChipElevation] used to resolve the elevation for this chip in
+ * different states. This controls the size of the shadow below the chip. Additionally, when the
+ * container color is [ColorScheme.surface], this controls the amount of primary color applied as an
+ * overlay. See [FilterChipDefaults.filterChipElevation].
+ * @param shape defines the shape of this chip's container, border (when [border] is not null), and
+ * shadow (when using [elevation])
+ * @param border the border to draw around the container of this chip. Pass `null` for no border.
+ * See [FilterChipDefaults.filterChipBorder].
+ * @param colors [SelectableChipColors] that will be used to resolve the colors used for this chip
+ * in different states. See [FilterChipDefaults.filterChipColors].
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -324,32 +320,31 @@
  * Example of an elevated FilterChip with a trailing icon:
  * @sample androidx.compose.material3.samples.ElevatedFilterChipSample
  *
- * @param selected Whether the chip is selected
- * @param onClick Called when the chip is clicked. If null, then this chip will be considered
- * read-only unless something else handles its input events and updates its state.
- * @param label A text label for this chip
- * @param modifier Modifier to be applied to the chip
- * @param enabled When disabled, chip will not respond to user input. It will also appear visually
- * disabled and disabled to accessibility services.
- * @param leadingIcon Optional icon at the start of the chip, preceding the [label] text.
- * @param selectedIcon Optional icon at the start of the chip, preceding the [label] text, that will
- * de displayed when the chip is selected, instead of any given [leadingIcon].
- * @param trailingIcon Optional icon at the end of the chip.
- * @param interactionSource The [MutableInteractionSource] represents the stream of [Interaction]s
- * for this chip. You can create and pass in your own remembered [MutableInteractionSource] if you
- * want to observe [Interaction]s and customize the appearance / behavior of this chip in
- * different [Interaction]s
- * @param elevation [SelectableChipElevation] used to resolve the elevation for this chip. The
- * resolved value controls the size of the shadow below the chip, as well as its tonal elevation.
- * When chip's container color is [ColorScheme.surface], a higher tonal elevation value will result
- * in a darker chip color in light theme and lighter color in dark theme. See also [Surface] and
- * [FilterChipDefaults.elevatedFilterChipElevation].
- * @param shape Defines the chip's shape as well its shadow. A shadow is only displayed if the
- * [elevation] is resolved to be greater than zero.
- * @param border [SelectableChipBorder] that will be used to resolve the border to draw around the
- * chip. Pass `null` here for no border.
- * @param colors [SelectableChipColors] that will be used to resolve the container and content color
- * for this chip in different states. See [FilterChipDefaults.elevatedFilterChipColors].
+ * @param selected whether this chip is selected or not
+ * @param onClick called when this chip is clicked. If `null`, then this chip will not be
+ * interactable, unless something else handles its input events and updates its state.
+ * @param label text label for this chip
+ * @param modifier the [Modifier] to be applied to this chip
+ * @param enabled controls the enabled state of this chip. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param leadingIcon optional icon at the start of the chip, preceding the [label] text
+ * @param selectedIcon optional icon at the start of the chip, preceding the [label] text, which is
+ * displayed when the chip is selected, instead of any given [leadingIcon]
+ * @param trailingIcon optional icon at the end of the chip
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this chip. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this chip in different states.
+ * @param elevation [SelectableChipElevation] used to resolve the elevation for this chip in
+ * different states. This controls the size of the shadow below the chip. Additionally, when the
+ * container color is [ColorScheme.surface], this controls the amount of primary color applied as an
+ * overlay. See [FilterChipDefaults.filterChipElevation].
+ * @param shape defines the shape of this chip's container, border (when [border] is not null), and
+ * shadow (when using [elevation])
+ * @param border the border to draw around the container of this chip. Pass `null` for no border.
+ * See [FilterChipDefaults.filterChipBorder].
+ * @param colors [SelectableChipColors] that will be used to resolve the colors used for this chip
+ * in different states. See [FilterChipDefaults.elevatedFilterChipColors].
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -411,30 +406,29 @@
  * Alternatively, use Accompanist's [Flow Layouts](https://google.github.io/accompanist/flowlayout/)
  * to wrap chips to a new line.
  *
- * @param onClick Called when the chip is clicked. If null, then this chip will be considered
- * read-only unless something else handles its input events and updates its state.
- * @param label A text label for this chip
- * @param modifier Modifier to be applied to the chip
- * @param enabled When disabled, chip will not respond to user input. It will also appear visually
- * disabled and disabled to accessibility services.
- * @param leadingIcon Optional icon at the start of the chip, preceding the [label] text.
- * @param avatar Optional avatar at the start of the chip, preceding the [label] text.
- * @param trailingIcon Optional icon at the end of the chip.
- * @param interactionSource The [MutableInteractionSource] represents the stream of [Interaction]s
- * for this chip. You can create and pass in your own remembered [MutableInteractionSource] if you
- * want to observe [Interaction]s and customize the appearance / behavior of this chip in
- * different [Interaction]s
- * @param elevation [ChipElevation] used to resolve the elevation for this chip. The resolved value
- * controls the size of the shadow below the chip, as well as its tonal elevation. When
- * chip's container color is [ColorScheme.surface], a higher tonal elevation value will result in a
- * darker chip color in light theme and lighter color in dark theme. See also [Surface] and
+ * @param onClick called when this chip is clicked. If `null`, then this chip will not be
+ * interactable, unless something else handles its input events and updates its state.
+ * @param label text label for this chip
+ * @param modifier the [Modifier] to be applied to this chip
+ * @param enabled controls the enabled state of this chip. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param leadingIcon optional icon at the start of the chip, preceding the [label] text
+ * @param avatar optional avatar at the start of the chip, preceding the [label] text
+ * @param trailingIcon optional icon at the end of the chip
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this chip. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this chip in different states.
+ * @param elevation [ChipElevation] used to resolve the elevation for this chip in different states.
+ * This controls the size of the shadow below the chip. Additionally, when the container color is
+ * [ColorScheme.surface], this controls the amount of primary color applied as an overlay. See
  * [InputChipDefaults.inputChipElevation].
- * @param shape Defines the chip's shape as well its shadow. A shadow is only displayed if the
- * [elevation] is resolved to be greater than zero.
- * @param border [ChipBorder] that will be used to resolve the border to draw around the chip. Pass
- * `null` here for no border. See [InputChipDefaults.inputChipBorder]
- * @param colors [ChipColors] that will be used to resolve the container and content color for this
- * chip in different states. See [InputChipDefaults.inputChipColors].
+ * @param shape defines the shape of this chip's container, border (when [border] is not null), and
+ * shadow (when using [elevation])
+ * @param border the border to draw around the container of this chip. Pass `null` for no border.
+ * See [InputChipDefaults.inputChipBorder].
+ * @param colors [ChipColors] that will be used to resolve the colors used for this chip in
+ * different states. See [InputChipDefaults.inputChipColors].
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -516,28 +510,27 @@
  * Example of a flat SuggestionChip with a trailing icon:
  * @sample androidx.compose.material3.samples.SuggestionChipSample
  *
- * @param onClick Called when the chip is clicked. If null, then this chip will be considered
- * read-only unless something else handles its input events and updates its state.
- * @param label A text label for this chip
- * @param modifier Modifier to be applied to the chip
- * @param enabled When disabled, chip will not respond to user input. It will also appear visually
- * disabled and disabled to accessibility services.
- * @param icon Optional icon at the start of the chip, preceding the [label] text.
- * @param interactionSource The [MutableInteractionSource] represents the stream of [Interaction]s
- * for this chip. You can create and pass in your own remembered [MutableInteractionSource] if you
- * want to observe [Interaction]s and customize the appearance / behavior of this chip in
- * different [Interaction]s
- * @param elevation [ChipElevation] used to resolve the elevation for this chip. The resolved value
- * controls the size of the shadow below the chip, as well as its tonal elevation. When
- * chip's container color is [ColorScheme.surface], a higher tonal elevation value will result in a
- * darker chip color in light theme and lighter color in dark theme. See also [Surface] and
+ * @param onClick called when this chip is clicked. If `null`, then this chip will not be
+ * interactable, unless something else handles its input events and updates its state.
+ * @param label text label for this chip
+ * @param modifier the [Modifier] to be applied to this chip
+ * @param enabled controls the enabled state of this chip. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param icon optional icon at the start of the chip, preceding the [label] text
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this chip. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this chip in different states.
+ * @param elevation [ChipElevation] used to resolve the elevation for this chip in different states.
+ * This controls the size of the shadow below the chip. Additionally, when the container color is
+ * [ColorScheme.surface], this controls the amount of primary color applied as an overlay. See
  * [SuggestionChipDefaults.suggestionChipElevation].
- * @param shape Defines the chip's shape as well its shadow. A shadow is only displayed if the
- * [elevation] is resolved to be greater than zero.
- * @param border [ChipBorder] that will be used to resolve the border to draw around the chip. Pass
- * `null` here for no border. See [SuggestionChipDefaults.suggestionChipBorder].
- * @param colors [ChipColors] that will be used to resolve the container and content color for this
- * chip in different states. See [SuggestionChipDefaults.suggestionChipColors].
+ * @param shape defines the shape of this chip's container, border (when [border] is not null), and
+ * shadow (when using [elevation])
+ * @param border the border to draw around the container of this chip. Pass `null` for no border.
+ * See [SuggestionChipDefaults.suggestionChipBorder].
+ * @param colors [ChipColors] that will be used to resolve the colors used for this chip in
+ * different states. See [SuggestionChipDefaults.suggestionChipColors].
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -592,30 +585,26 @@
  * Example of an elevated SuggestionChip with a trailing icon:
  * @sample androidx.compose.material3.samples.ElevatedSuggestionChipSample
  *
- * @param onClick Called when the chip is clicked. If null, then this chip will be considered
- * read-only unless something else handles its input events and updates its state.
- * @param label A text label for this chip
- * @param modifier Modifier to be applied to the chip
- * @param enabled When disabled, chip will not respond to user input. It will also appear visually
- * disabled and disabled to accessibility services.
- * @param icon Optional icon at the start of the chip, preceding the [label] text.
- * @param interactionSource The [MutableInteractionSource] represents the stream of [Interaction]s
- * for this chip. You can create and pass in your own remembered [MutableInteractionSource] if you
- * want to observe [Interaction]s and customize the appearance / behavior of this chip in
- * different [Interaction]s
- * @param elevation [ChipElevation] used to resolve the elevation for this chip. The resolved value
- * controls the size of the shadow below the chip, as well as its tonal elevation. When
- * chip's container color is [ColorScheme.surface], a higher tonal elevation value will result in a
- * darker chip color in light theme and lighter color in dark theme. See also [Surface],
- * [SuggestionChipDefaults.suggestionChipElevation], and
- * [SuggestionChipDefaults.elevatedSuggestionChipElevation].
- * @param shape Defines the chip's shape as well its shadow. A shadow is only displayed if the
- * [elevation] is resolved to be greater than zero.
- * @param border [ChipBorder] that will be used to resolve the border to draw around the chip. Pass
- * `null` here for no border. See [SuggestionChipDefaults.suggestionChipBorder].
- * @param colors [ChipColors] that will be used to resolve the container and content color for this
- * chip in different states. See [SuggestionChipDefaults.suggestionChipColors] and
- * [SuggestionChipDefaults.elevatedSuggestionChipColors].
+ * @param onClick called when this chip is clicked. If `null`, then this chip will not be
+ * interactable, unless something else handles its input events and updates its state.
+ * @param label text label for this chip
+ * @param modifier the [Modifier] to be applied to this chip
+ * @param enabled controls the enabled state of this chip. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param icon optional icon at the start of the chip, preceding the [label] text
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this chip. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this chip in different states.
+ * @param elevation [ChipElevation] used to resolve the elevation for this chip in different states.
+ * This controls the size of the shadow below the chip. Additionally, when the container color is
+ * [ColorScheme.surface], this controls the amount of primary color applied as an overlay. See
+ * [Surface] and [SuggestionChipDefaults.elevatedSuggestionChipElevation].
+ * @param shape defines the shape of this chip's container, border (when [border] is not null), and
+ * shadow (when using [elevation])
+ * @param border the border to draw around the container of this chip
+ * @param colors [ChipColors] that will be used to resolve the colors used for this chip in
+ * different states. See [SuggestionChipDefaults.elevatedSuggestionChipColors].
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -659,14 +648,14 @@
 @ExperimentalMaterial3Api
 interface ChipElevation {
     /**
-     * Represents the tonal elevation used in a chip, depending on [enabled] and
+     * Represents the tonal elevation used in a chip, depending on its [enabled] state and
      * [interactionSource]. This should typically be the same value as the [shadowElevation].
      *
      * Tonal elevation is used to apply a color shift to the surface to give the it higher emphasis.
      * When surface's color is [ColorScheme.surface], a higher elevation will result in a darker
      * color in light theme and lighter color in dark theme.
      *
-     * See [shadowElevation] which controls the elevation of the shadow drawn around the Chip.
+     * See [shadowElevation] which controls the elevation of the shadow drawn around the chip.
      *
      * @param enabled whether the chip is enabled
      * @param interactionSource the [InteractionSource] for this chip
@@ -675,10 +664,10 @@
     fun tonalElevation(enabled: Boolean, interactionSource: InteractionSource): State<Dp>
 
     /**
-     * Represents the shadow elevation used in a chip, depending on [enabled] and
+     * Represents the shadow elevation used in a chip, depending on its [enabled] state and
      * [interactionSource]. This should typically be the same value as the [tonalElevation].
      *
-     * Shadow elevation is used to apply a shadow around the surface to give it higher emphasis.
+     * Shadow elevation is used to apply a shadow around the chip to give it higher emphasis.
      *
      * See [tonalElevation] which controls the elevation with a color shift to the surface.
      *
@@ -746,7 +735,7 @@
 @ExperimentalMaterial3Api
 interface ChipColors {
     /**
-     * Represents the container  color for this chip, depending on [enabled].
+     * Represents the container color for this chip, depending on [enabled].
      *
      * @param enabled whether the chip is enabled
      */
@@ -779,7 +768,7 @@
 }
 
 /**
- * Represents the container  and content colors used in a selectable chip in different states.
+ * Represents the container and content colors used in a selectable chip in different states.
  *
  * See [FilterChipDefaults.filterChipColors] and [FilterChipDefaults.elevatedFilterChipColors] for
  * the default colors used in [FilterChip].
@@ -788,7 +777,7 @@
 @ExperimentalMaterial3Api
 interface SelectableChipColors {
     /**
-     * Represents the container  color for this chip, depending on [enabled] and [selected].
+     * Represents the container color for this chip, depending on [enabled] and [selected].
      *
      * @param enabled whether the chip is enabled
      * @param selected whether the chip is selected
@@ -846,7 +835,6 @@
 @Stable
 @ExperimentalMaterial3Api
 interface SelectableChipBorder {
-
     /**
      * Represents the [BorderStroke] stroke used for this chip, depending on [enabled] and
      * [selected].
@@ -1203,7 +1191,7 @@
 
     /**
      * Creates a [SelectableChipColors] that represents the default container and content colors
-     * used in a elevated [FilterChip].
+     * used in an elevated [FilterChip].
      *
      * @param containerColor the container color of this chip when enabled
      * @param labelColor the label color of this chip when enabled

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Divider.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Divider.kt
index 93f5a7c..2ee204f 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Divider.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Divider.kt

@@ -37,10 +37,11 @@
  *
  * ![Divider image](https://developer.android.com/images/reference/androidx/compose/material3/divider.png)
  *
- * @param color color of the divider line
- * @param thickness thickness of the divider line
- * Using [Dp.Hairline] will produce a single pixel divider regardless of screen density
- * @param startIndent start offset of this line, no offset by default
+ * @param modifier the [Modifier] to be applied to this divider line
+ * @param color color of this divider line
+ * @param thickness thickness of this divider line. Using [Dp.Hairline] will produce a single pixel
+ * divider regardless of screen density.
+ * @param startIndent start offset of this line. No offset by default.
  */
 @Composable
 fun Divider(

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/FloatingActionButton.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/FloatingActionButton.kt
index 2ba8dc0..d13a1d7 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/FloatingActionButton.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/FloatingActionButton.kt

@@ -71,20 +71,22 @@
  *
  * @sample androidx.compose.material3.samples.FloatingActionButtonSample
  *
- * @param onClick callback invoked when this FAB is clicked
- * @param modifier [Modifier] to be applied to this FAB.
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this FAB. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this FAB in different [Interaction]s.
- * @param shape The [Shape] of this FAB
- * @param containerColor The container color. Use [Color.Transparent] to have no color
- * @param contentColor The preferred content color for content inside this FAB
- * @param elevation [FloatingActionButtonElevation] used to resolve the elevation for this FAB
- * in different states. This controls the size of the shadow below the FAB. When [containerColor]
- * is [ColorScheme.surface], a higher elevation (surface blended with more primary) will result in
- * a darker surface color in light theme and lighter color in dark theme.
- * @param content the content of this FAB - this is typically an [Icon].
+ * @param onClick called when this FAB is clicked
+ * @param modifier the [Modifier] to be applied to this FAB
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this FAB. You can create and pass in your own `remember`ed instance to observe [Interaction]s
+ * and customize the appearance / behavior of this FAB in different states.
+ * @param shape defines the shape of this FAB's container and shadow (when using [elevation])
+ * @param containerColor the color used for the background of this FAB. Use [Color.Transparent] to
+ * have no color.
+ * @param contentColor the preferred color for content inside this FAB. Defaults to either the
+ * matching content color for [containerColor], or to the current [LocalContentColor] if
+ * [containerColor] is not a color from the theme.
+ * @param elevation [FloatingActionButtonElevation] used to resolve the elevation for this FAB in
+ * different states. This controls the size of the shadow below the FAB. Additionally, when the
+ * container color is [ColorScheme.surface], this controls the amount of primary color applied as an
+ * overlay. See also: [Surface].
+ * @param content the content of this FAB, typically an [Icon]
  */
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
@@ -138,20 +140,22 @@
  *
  * @sample androidx.compose.material3.samples.SmallFloatingActionButtonSample
  *
- * @param onClick callback invoked when this FAB is clicked
- * @param modifier [Modifier] to be applied to this FAB.
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this FAB. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this FAB in different [Interaction]s.
- * @param shape The [Shape] of this FAB
- * @param containerColor The container color. Use [Color.Transparent] to have no color
- * @param contentColor The preferred content color for content inside this FAB
- * @param elevation [FloatingActionButtonElevation] used to resolve the elevation for this FAB
- * in different states. This controls the size of the shadow below the FAB. When [containerColor]
- * is [ColorScheme.surface], a higher elevation (surface blended with more primary) will result in
- * a darker surface color in light theme and lighter color in dark theme.
- * @param content the content of this FAB - this is typically an [Icon].
+ * @param onClick called when this FAB is clicked
+ * @param modifier the [Modifier] to be applied to this FAB
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this FAB. You can create and pass in your own `remember`ed instance to observe [Interaction]s
+ * and customize the appearance / behavior of this FAB in different states.
+ * @param shape defines the shape of this FAB's container and shadow (when using [elevation])
+ * @param containerColor the color used for the background of this FAB. Use [Color.Transparent] to
+ * have no color.
+ * @param contentColor the preferred color for content inside this FAB. Defaults to either the
+ * matching content color for [containerColor], or to the current [LocalContentColor] if
+ * [containerColor] is not a color from the theme.
+ * @param elevation [FloatingActionButtonElevation] used to resolve the elevation for this FAB in
+ * different states. This controls the size of the shadow below the FAB. Additionally, when the
+ * container color is [ColorScheme.surface], this controls the amount of primary color applied as an
+ * overlay. See also: [Surface].
+ * @param content the content of this FAB, typically an [Icon]
  */
 @Composable
 fun SmallFloatingActionButton(
@@ -188,20 +192,22 @@
  *
  * @sample androidx.compose.material3.samples.LargeFloatingActionButtonSample
  *
- * @param onClick callback invoked when this FAB is clicked
- * @param modifier [Modifier] to be applied to this FAB.
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this FAB. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this FAB in different [Interaction]s.
- * @param shape The [Shape] of this FAB
- * @param containerColor The container color. Use [Color.Transparent] to have no color
- * @param contentColor The preferred content color for content inside this FAB
- * @param elevation [FloatingActionButtonElevation] used to resolve the elevation for this FAB
- * in different states. This controls the size of the shadow below the FAB. When [containerColor]
- * is [ColorScheme.surface], a higher elevation (surface blended with more primary) will result in
- * a darker surface color in light theme and lighter color in dark theme.
- * @param content the content of this FAB - this is typically an [Icon].
+ * @param onClick called when this FAB is clicked
+ * @param modifier the [Modifier] to be applied to this FAB
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this FAB. You can create and pass in your own `remember`ed instance to observe [Interaction]s
+ * and customize the appearance / behavior of this FAB in different states.
+ * @param shape defines the shape of this FAB's container and shadow (when using [elevation])
+ * @param containerColor the color used for the background of this FAB. Use [Color.Transparent] to
+ * have no color.
+ * @param contentColor the preferred color for content inside this FAB. Defaults to either the
+ * matching content color for [containerColor], or to the current [LocalContentColor] if
+ * [containerColor] is not a color from the theme.
+ * @param elevation [FloatingActionButtonElevation] used to resolve the elevation for this FAB in
+ * different states. This controls the size of the shadow below the FAB. Additionally, when the
+ * container color is [ColorScheme.surface], this controls the amount of primary color applied as an
+ * overlay. See also: [Surface].
+ * @param content the content of this FAB, typically an [Icon]
  */
 @Composable
 fun LargeFloatingActionButton(
@@ -241,20 +247,22 @@
  *
  * @sample androidx.compose.material3.samples.ExtendedFloatingActionButtonTextSample
  *
- * @param onClick callback invoked when this FAB is clicked
- * @param modifier [Modifier] to be applied to this FAB
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this FAB. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this FAB in different [Interaction]s.
- * @param shape The [Shape] of this FAB
- * @param containerColor The container color. Use [Color.Transparent] to have no color
- * @param contentColor The preferred content color for content inside this FAB
- * @param elevation [FloatingActionButtonElevation] used to resolve the elevation for this FAB
- * in different states. This controls the size of the shadow below the FAB. When [containerColor]
- * is [ColorScheme.surface], a higher elevation (surface blended with more primary) will result in
- * a darker surface color in light theme and lighter color in dark theme.
- * @param content the content of this FAB - this is typically an [Text] label.
+ * @param onClick called when this FAB is clicked
+ * @param modifier the [Modifier] to be applied to this FAB
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this FAB. You can create and pass in your own `remember`ed instance to observe [Interaction]s
+ * and customize the appearance / behavior of this FAB in different states.
+ * @param shape defines the shape of this FAB's container and shadow (when using [elevation])
+ * @param containerColor the color used for the background of this FAB. Use [Color.Transparent] to
+ * have no color.
+ * @param contentColor the preferred color for content inside this FAB. Defaults to either the
+ * matching content color for [containerColor], or to the current [LocalContentColor] if
+ * [containerColor] is not a color from the theme.
+ * @param elevation [FloatingActionButtonElevation] used to resolve the elevation for this FAB in
+ * different states. This controls the size of the shadow below the FAB. Additionally, when the
+ * container color is [ColorScheme.surface], this controls the amount of primary color applied as an
+ * overlay. See also: [Surface].
+ * @param content the content of this FAB, typically a [Text] label
  */
 @Composable
 fun ExtendedFloatingActionButton(
@@ -297,25 +305,25 @@
  * @sample androidx.compose.material3.samples.ExtendedFloatingActionButtonSample
  * @sample androidx.compose.material3.samples.AnimatedExtendedFloatingActionButtonSample
  *
- * @param text Text label displayed inside this FAB
- * @param icon Optional icon for this FAB, typically this will be a
- * [Icon].
- * @param onClick callback invoked when this FAB is clicked
- * @param modifier [Modifier] to be applied to this FAB
- * @param expanded The FAB will animate between expanded state and collapsed state. In an expanded
- * state the FAB will show both the [icon] and [text] parameters. In a collapsed state the FAB will
- * show only the [icon] parameter.
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this FAB. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this FAB in different [Interaction]s.
- * @param shape The [Shape] of this FAB
- * @param containerColor The container color. Use [Color.Transparent] to have no color
- * @param contentColor The preferred content color for content inside this FAB
- * @param elevation [FloatingActionButtonElevation] used to resolve the elevation for this FAB
- * in different states. This controls the size of the shadow below the FAB. When [containerColor]
- * is [ColorScheme.surface], a higher elevation (surface blended with more primary) will result in
- * a darker surface color in light theme and lighter color in dark theme.
+ * @param text label displayed inside this FAB
+ * @param icon optional icon for this FAB, typically an [Icon]
+ * @param onClick called when this FAB is clicked
+ * @param modifier the [Modifier] to be applied to this FAB
+ * @param expanded controls the expansion state of this FAB. In an expanded state, the FAB will show
+ * both the [icon] and [text]. In a collapsed state, the FAB will show only the [icon].
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this FAB. You can create and pass in your own `remember`ed instance to observe [Interaction]s
+ * and customize the appearance / behavior of this FAB in different states.
+ * @param shape defines the shape of this FAB's container and shadow (when using [elevation])
+ * @param containerColor the color used for the background of this FAB. Use [Color.Transparent] to
+ * have no color.
+ * @param contentColor the preferred color for content inside this FAB. Defaults to either the
+ * matching content color for [containerColor], or to the current [LocalContentColor] if
+ * [containerColor] is not a color from the theme.
+ * @param elevation [FloatingActionButtonElevation] used to resolve the elevation for this FAB in
+ * different states. This controls the size of the shadow below the FAB. Additionally, when the
+ * container color is [ColorScheme.surface], this controls the amount of primary color applied as an
+ * overlay. See also: [Surface].
  */
 @Composable
 fun ExtendedFloatingActionButton(
@@ -376,8 +384,8 @@
      * [interactionSource]. This should typically be the same value as the [shadowElevation].
      *
      * Tonal elevation is used to apply a color shift to the surface to give the it higher emphasis.
-     * When surface's color is [ColorScheme.surface], a higher the elevation will result
-     * in a darker color in light theme and lighter color in dark theme.
+     * When surface's color is [ColorScheme.surface], a higher the elevation will result in a darker
+     * color in light theme and lighter color in dark theme.
      *
      * See [shadowElevation] which controls the elevation of the shadow drawn around the FAB.
      *
@@ -390,7 +398,7 @@
      * Represents the shadow elevation used in a floating action button, depending on
      * [interactionSource]. This should typically be the same value as the [tonalElevation].
      *
-     * Shadow elevation is used to apply a shadow around the surface to give it higher emphasis.
+     * Shadow elevation is used to apply a shadow around the FAB to give it higher emphasis.
      *
      * See [tonalElevation] which controls the elevation with a color shift to the surface.
      *

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Icon.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Icon.kt
index 6b32217..b6e492a 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Icon.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Icon.kt

@@ -43,14 +43,14 @@
  *
  * To learn more about icons, see [Material Design icons](https://m3.material.io/styles/icons/overview)
  *
- * @param imageVector [ImageVector] to draw inside this Icon
+ * @param imageVector [ImageVector] to draw inside this icon
  * @param contentDescription text used by accessibility services to describe what this icon
  * represents. This should always be provided unless this icon is used for decorative purposes, and
  * does not represent a meaningful action that a user can take. This text should be localized, such
  * as by using [androidx.compose.ui.res.stringResource] or similar
- * @param modifier optional [Modifier] for this Icon
+ * @param modifier the [Modifier] to be applied to this icon
  * @param tint tint to be applied to [imageVector]. If [Color.Unspecified] is provided, then no tint
- * is applied
+ * is applied.
  */
 @Composable
 fun Icon(
@@ -73,14 +73,14 @@
  *
  * To learn more about icons, see [Material Design icons](https://m3.material.io/styles/icons/overview)
  *
- * @param bitmap [ImageBitmap] to draw inside this Icon
+ * @param bitmap [ImageBitmap] to draw inside this icon
  * @param contentDescription text used by accessibility services to describe what this icon
  * represents. This should always be provided unless this icon is used for decorative purposes, and
  * does not represent a meaningful action that a user can take. This text should be localized, such
  * as by using [androidx.compose.ui.res.stringResource] or similar
- * @param modifier optional [Modifier] for this Icon
+ * @param modifier the [Modifier] to be applied to this icon
  * @param tint tint to be applied to [bitmap]. If [Color.Unspecified] is provided, then no tint is
- * applied
+ * applied.
  */
 @Composable
 fun Icon(
@@ -104,14 +104,14 @@
  *
  * To learn more about icons, see [Material Design icons](https://m3.material.io/styles/icons/overview)
  *
- * @param painter [Painter] to draw inside this Icon
+ * @param painter [Painter] to draw inside this icon
  * @param contentDescription text used by accessibility services to describe what this icon
  * represents. This should always be provided unless this icon is used for decorative purposes, and
  * does not represent a meaningful action that a user can take. This text should be localized, such
  * as by using [androidx.compose.ui.res.stringResource] or similar
- * @param modifier optional [Modifier] for this Icon
+ * @param modifier the [Modifier] to be applied to this icon
  * @param tint tint to be applied to [painter]. If [Color.Unspecified] is provided, then no tint is
- * applied
+ * applied.
  */
 @Composable
 fun Icon(

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/IconButton.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/IconButton.kt
index e3d0489..3521aef 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/IconButton.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/IconButton.kt

@@ -58,18 +58,17 @@
  *
  * @sample androidx.compose.material3.samples.IconButtonSample
  *
- * @param onClick callback to be called when the icon button is clicked
- * @param modifier Modifier to be applied to the layout of the icon button
- * @param enabled whether or not this icon button will handle input events and appear enabled for
- * semantics purposes
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this icon button. You can create and pass in your own remembered
- * [MutableInteractionSource] to observe [Interaction]s that will customize the appearance
- * / behavior of this icon button in different states
- * @param colors an [IconButtonColors] that will be used to resolve the colors used for this icon
+ * @param onClick called when this icon button is clicked
+ * @param modifier the [Modifier] to be applied to this icon button
+ * @param enabled controls the enabled state of this icon button. When `false`, this component will
+ * not respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this icon button. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this icon button in different states.
+ * @param colors [IconButtonColors] that will be used to resolve the colors used for this icon
  * button in different states. See [IconButtonDefaults.iconButtonColors].
- * @param content the content (icon) to be drawn inside the icon button. This is typically an
- * [Icon].
+ * @param content the content of this icon button, typically an [Icon]
  */
 @Composable
 fun IconButton(
@@ -118,19 +117,18 @@
  *
  * @sample androidx.compose.material3.samples.IconToggleButtonSample
  *
- * @param checked whether or not this icon button is toggled on or off
- * @param onCheckedChange callback to be invoked when the toggleable icon button is clicked
- * @param modifier Modifier to be applied to the layout of the icon button
- * @param enabled whether or not this icon button will handle input events and appear enabled for
- * semantics purposes
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this icon button. You can create and pass in your own remembered
- * [MutableInteractionSource] to observe [Interaction]s that will customize the appearance
- * / behavior of this icon button in different states
- * @param colors an [IconToggleButtonColors] that will be used to resolve the colors used for this
- * icon button in different states. See [IconButtonDefaults.iconToggleButtonColors].
- * @param content the content (icon) to be drawn inside the icon button. This is typically an
- * [Icon].
+ * @param checked whether this icon button is toggled on or off
+ * @param onCheckedChange called when this icon button is clicked
+ * @param modifier the [Modifier] to be applied to this icon button
+ * @param enabled controls the enabled state of this icon button. When `false`, this component will
+ * not respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this icon button. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this icon button in different states.
+ * @param colors [IconToggleButtonColors] that will be used to resolve the colors used for this icon
+ * button in different states. See [IconButtonDefaults.iconToggleButtonColors].
+ * @param content the content of this icon button, typically an [Icon]
  */
 @Composable
 fun IconToggleButton(
@@ -182,19 +180,18 @@
  * Filled icon button sample:
  * @sample androidx.compose.material3.samples.FilledIconButtonSample
  *
- * @param onClick callback to be called when the icon button is clicked
- * @param modifier Modifier to be applied to the layout of the icon button
- * @param enabled whether or not this icon button will handle input events and appear enabled for
- * semantics purposes
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this icon button. You can create and pass in your own remembered
- * [MutableInteractionSource] to observe [Interaction]s that will customize the appearance
- * / behavior of this icon button in different states
- * @param shape defines the icon button's shape
- * @param colors an [IconButtonColors] that will be used to resolve the colors used for this icon
+ * @param onClick called when this icon button is clicked
+ * @param modifier the [Modifier] to be applied to this icon button
+ * @param enabled controls the enabled state of this icon button. When `false`, this component will
+ * not respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this icon button. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this icon button in different states.
+ * @param shape defines the shape of this icon button's container
+ * @param colors [IconButtonColors] that will be used to resolve the colors used for this icon
  * button in different states. See [IconButtonDefaults.filledIconButtonColors].
- * @param content the content (icon) to be drawn inside the icon button. This is typically an
- * [Icon].
+ * @param content the content of this icon button, typically an [Icon]
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -244,19 +241,18 @@
  * Filled tonal icon button sample:
  * @sample androidx.compose.material3.samples.FilledTonalIconButtonSample
  *
- * @param onClick callback to be called when the icon button is clicked
- * @param modifier Modifier to be applied to the layout of the icon button
- * @param enabled whether or not this icon button will handle input events and appear enabled for
- * semantics purposes
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this icon button. You can create and pass in your own remembered
- * [MutableInteractionSource] to observe [Interaction]s that will customize the appearance
- * / behavior of this icon button in different states
- * @param shape defines the icon button's shape
- * @param colors an [IconButtonColors] that will be used to resolve the colors used for this icon
+ * @param onClick called when this icon button is clicked
+ * @param modifier the [Modifier] to be applied to this icon button
+ * @param enabled controls the enabled state of this icon button. When `false`, this component will
+ * not respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this icon button. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this icon button in different states.
+ * @param shape defines the shape of this icon button's container
+ * @param colors [IconButtonColors] that will be used to resolve the colors used for this icon
  * button in different states. See [IconButtonDefaults.filledIconButtonColors].
- * @param content the content (icon) to be drawn inside the icon button. This is typically an
- * [Icon].
+ * @param content the content of this icon button, typically an [Icon]
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -301,20 +297,19 @@
  * Toggleable filled icon button sample:
  * @sample androidx.compose.material3.samples.FilledIconToggleButtonSample
  *
- * @param checked whether or not this icon button is toggled on or off
- * @param onCheckedChange callback to be invoked when the toggleable icon button is clicked
- * @param modifier Modifier to be applied to the layout of the icon button
- * @param enabled whether or not this icon button will handle input events and appear enabled for
- * semantics purposes
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this icon button. You can create and pass in your own remembered
- * [MutableInteractionSource] to observe [Interaction]s that will customize the appearance
- * / behavior of this icon button in different states
- * @param shape defines the icon button's shape
- * @param colors an [IconToggleButtonColors] that will be used to resolve the colors used for
- * this icon button in different states. See [IconButtonDefaults.filledIconToggleButtonColors].
- * @param content the content (icon) to be drawn inside the icon button. This is typically an
- * [Icon].
+ * @param checked whether this icon button is toggled on or off
+ * @param onCheckedChange called when this icon button is clicked
+ * @param modifier the [Modifier] to be applied to this icon button
+ * @param enabled controls the enabled state of this icon button. When `false`, this component will
+ * not respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this icon button. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this icon button in different states.
+ * @param shape defines the shape of this icon button's container
+ * @param colors [IconToggleButtonColors] that will be used to resolve the colors used for this icon
+ * button in different states. See [IconButtonDefaults.filledIconToggleButtonColors].
+ * @param content the content of this icon button, typically an [Icon]
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -366,20 +361,19 @@
  * Toggleable filled tonal icon button sample:
  * @sample androidx.compose.material3.samples.FilledTonalIconToggleButtonSample
  *
- * @param checked whether or not this icon button is toggled on or off
- * @param onCheckedChange callback to be invoked when the toggleable icon button is clicked
- * @param modifier Modifier to be applied to the layout of the icon button
- * @param enabled whether or not this icon button will handle input events and appear enabled for
- * semantics purposes
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this icon button. You can create and pass in your own remembered
- * [MutableInteractionSource] to observe [Interaction]s that will customize the appearance
- * / behavior of this icon button in different states
- * @param shape defines the icon button's shape
- * @param colors an [IconToggleButtonColors] that will be used to resolve the colors used for
- * this icon button in different states. See [IconButtonDefaults.filledIconToggleButtonColors].
- * @param content the content (icon) to be drawn inside the icon button. This is typically an
- * [Icon].
+ * @param checked whether this icon button is toggled on or off
+ * @param onCheckedChange called when this icon button is clicked
+ * @param modifier the [Modifier] to be applied to this icon button
+ * @param enabled controls the enabled state of this icon button. When `false`, this component will
+ * not respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this icon button. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this icon button in different states.
+ * @param shape defines the shape of this icon button's container
+ * @param colors [IconToggleButtonColors] that will be used to resolve the colors used for this icon
+ * button in different states. See [IconButtonDefaults.filledIconToggleButtonColors].
+ * @param content the content of this icon button, typically an [Icon]
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -431,20 +425,21 @@
  *
  * @sample androidx.compose.material3.samples.OutlinedIconButtonSample
  *
- * @param onClick callback to be called when the icon button is clicked
- * @param modifier Modifier to be applied to the layout of the icon button
- * @param enabled whether or not this icon button will handle input events and appear enabled for
- * semantics purposes
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this icon button. You can create and pass in your own remembered
- * [MutableInteractionSource] to observe [Interaction]s that will customize the appearance
- * / behavior of this icon button in different states
- * @param shape defines the icon button's shape
- * @param border defines the icon button's border.See [IconButtonDefaults.outlinedIconButtonBorder].
- * @param colors an [IconButtonColors] that will be used to resolve the colors used for this icon
+ * @param onClick called when this icon button is clicked
+ * @param modifier the [Modifier] to be applied to this icon button
+ * @param enabled controls the enabled state of this icon button. When `false`, this component will
+ * not respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this icon button. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this icon button in different states.
+ * @param shape defines the shape of this icon button's container and border (when [border] is not
+ * null)
+ * @param border the border to draw around the container of this icon button. Pass `null` for no
+ * border. See [IconButtonDefaults.outlinedIconButtonBorder].
+ * @param colors [IconButtonColors] that will be used to resolve the colors used for this icon
  * button in different states. See [IconButtonDefaults.outlinedIconButtonColors].
- * @param content the content (icon) to be drawn inside the icon button. This is typically an
- * [Icon].
+ * @param content the content of this icon button, typically an [Icon]
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -490,22 +485,22 @@
  *
  * @sample androidx.compose.material3.samples.OutlinedIconToggleButtonSample
  *
- * @param checked whether or not this icon button is toggled on or off
- * @param onCheckedChange callback to be invoked when the toggleable icon button is clicked
- * @param modifier Modifier to be applied to the layout of the icon button
- * @param enabled whether or not this icon button will handle input events and appear enabled for
- * semantics purposes
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this icon button. You can create and pass in your own remembered
- * [MutableInteractionSource] to observe [Interaction]s that will customize the appearance
- * / behavior of this icon button in different states
- * @param shape defines the icon button's shape
- * @param border defines the icon button's border.See
- * [IconButtonDefaults.outlinedIconToggleButtonBorder]
- * @param colors an [IconToggleButtonColors] that will be used to resolve the colors used for
- * this icon button in different states. See [IconButtonDefaults.outlinedIconToggleButtonColors].
- * @param content the content (icon) to be drawn inside the icon button. This is typically an
- * [Icon].
+ * @param checked whether this icon button is toggled on or off
+ * @param onCheckedChange called when this icon button is clicked
+ * @param modifier the [Modifier] to be applied to this icon button
+ * @param enabled controls the enabled state of this icon button. When `false`, this component will
+ * not respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this icon button. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this icon button in different states.
+ * @param shape defines the shape of this icon button's container and border (when [border] is not
+ * null)
+ * @param border the border to draw around the container of this icon button. Pass `null` for no
+ * border. See [IconButtonDefaults.outlinedIconToggleButtonBorder].
+ * @param colors [IconToggleButtonColors] that will be used to resolve the colors used for this icon
+ * button in different states. See [IconButtonDefaults.outlinedIconToggleButtonColors].
+ * @param content the content of this icon button, typically an [Icon]
  */
 @ExperimentalMaterial3Api
 @Composable
@@ -549,7 +544,6 @@
  */
 @Stable
 interface IconButtonColors {
-
     /**
      * Represents the container color for this icon button, depending on [enabled].
      *
@@ -579,7 +573,6 @@
  */
 @Stable
 interface IconToggleButtonColors {
-
     /**
      * Represents the container color for this icon button, depending on [enabled] and [checked].
      *
@@ -603,7 +596,6 @@
  * Contains the default values used by all icon button types.
  */
 object IconButtonDefaults {
-
     /**
      * Creates a [IconButtonColors] that represents the default colors used in a [IconButton].
      *

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/NavigationBar.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/NavigationBar.kt
index e85a0c3..5fc7b6f 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/NavigationBar.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/NavigationBar.kt

@@ -72,16 +72,16 @@
  * See [NavigationBarItem] for configuration specific to each item, and not the overall
  * [NavigationBar] component.
  *
- * @param modifier optional [Modifier] for this NavigationBar
- * @param containerColor the container color for this NavigationBar
- * @param contentColor the preferred content color provided by this NavigationBar to its children.
- * Defaults to either the matching content color for [containerColor], or if [containerColor] is not
- * a color from the theme, this will keep the same value set above this NavigationBar.
- * @param tonalElevation When [containerColor] is [ColorScheme.surface], a higher tonal elevation
- * value will result in a darker color in light theme and lighter color in dark theme. See also:
- * [Surface].
- * @param content destinations inside this NavigationBar. This should contain multiple
- * [NavigationBarItem]s
+ * @param modifier the [Modifier] to be applied to this navigation bar
+ * @param containerColor the color used for the background of this navigation bar. Use
+ * [Color.Transparent] to have no color.
+ * @param contentColor the preferred color for content inside this navigation bar. Defaults to
+ * either the matching content color for [containerColor], or to the current [LocalContentColor] if
+ * [containerColor] is not a color from the theme.
+ * @param tonalElevation when [containerColor] is [ColorScheme.surface], a translucent primary color
+ * overlay is applied on top of the container. A higher tonal elevation value will result in a
+ * darker color in light theme and lighter color in dark theme. See also: [Surface].
+ * @param content the content of this navigation bar, typically 3-5 [NavigationBarItem]s
  */
 @Composable
 fun NavigationBar(
@@ -124,19 +124,20 @@
  * labels if not selected is controlled by [alwaysShowLabel].
  *
  * @param selected whether this item is selected
- * @param onClick the callback to be invoked when this item is selected
- * @param icon icon for this item, typically this will be an [Icon]
- * @param modifier optional [Modifier] for this item
- * @param enabled controls the enabled state of this item. When `false`, this item will not be
- * clickable and will appear disabled to accessibility services.
+ * @param onClick called when this item is clicked
+ * @param icon icon for this item, typically an [Icon]
+ * @param modifier the [Modifier] to be applied to this item
+ * @param enabled controls the enabled state of this item. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
  * @param label optional text label for this item
- * @param alwaysShowLabel whether to always show the label for this item. If false, the label will
+ * @param alwaysShowLabel whether to always show the label for this item. If `false`, the label will
  * only be shown when this item is selected.
  * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
- * for this NavigationBarItem. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the appearance /
- * behavior of this NavigationBarItem in different [Interaction]s.
- * @param colors the various colors used in elements of this item
+ * for this item. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this item in different states.
+ * @param colors [NavigationBarItemColors] that will be used to resolve the colors used for this
+ * item in different states. See [NavigationBarItemDefaults.colors].
  */
 @Composable
 fun RowScope.NavigationBarItem(
@@ -349,8 +350,8 @@
                 measurables
                     .first { it.layoutId == LabelLayoutIdTag }
                     .measure(
-                        // Measure with loose constraints for height as we don't want the label to take up more
-                        // space than it needs
+                        // Measure with loose constraints for height as we don't want the label to
+                        // take up more space than it needs
                         constraints.copy(minHeight = 0)
                     )
             }

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/NavigationDrawer.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/NavigationDrawer.kt
index 3ce3883..d60fdbf 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/NavigationDrawer.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/NavigationDrawer.kt

@@ -238,17 +238,19 @@
  *
  * @sample androidx.compose.material3.samples.ModalNavigationDrawerSample
  *
- * @param drawerContent composable that represents content inside the drawer
- * @param modifier optional modifier for the drawer
+ * @param drawerContent content inside this drawer
+ * @param modifier the [Modifier] to be applied to this drawer
  * @param drawerState state of the drawer
- * @param gesturesEnabled whether or not drawer can be interacted by gestures
- * @param drawerShape shape of the drawer container
- * @param drawerTonalElevation Affects the alpha of the color overlay applied on the container color
- * of the drawer container.
- * @param drawerContainerColor container color to be used for the drawer container
- * @param drawerContentColor color of the content to use inside the drawer container. Defaults to
- * either the matching content color for [drawerContainerColor], or, if it is not a color from
- * the theme, this will keep the same value set above this Surface.
+ * @param gesturesEnabled whether or not the drawer can be interacted by gestures
+ * @param drawerShape defines the shape of this drawer's container
+ * @param drawerTonalElevation when [drawerContainerColor] is [ColorScheme.surface], a translucent
+ * primary color overlay is applied on top of the container. A higher tonal elevation value will
+ * result in a darker color in light theme and lighter color in dark theme. See also: [Surface].
+ * @param drawerContainerColor the color used for the background of this drawer. Use
+ * [Color.Transparent] to have no color.
+ * @param drawerContentColor the preferred color for content inside this drawer. Defaults to either
+ * the matching content color for [drawerContainerColor], or to the current [LocalContentColor] if
+ * [drawerContainerColor] is not a color from the theme.
  * @param scrimColor color of the scrim that obscures content when the drawer is open
  * @param content content of the rest of the UI
  */
@@ -387,17 +389,19 @@
  *
  * @sample androidx.compose.material3.samples.DismissibleNavigationDrawerSample
  *
- * @param drawerContent composable that represents content inside the drawer
- * @param modifier optional modifier for the drawer
+ * @param drawerContent content inside this drawer
+ * @param modifier the [Modifier] to be applied to this drawer
  * @param drawerState state of the drawer
- * @param gesturesEnabled whether or not drawer can be interacted by gestures
- * @param drawerShape shape of the drawer container
- * @param drawerTonalElevation Affects the alpha of the color overlay applied on the container color
- * of the drawer container.
- * @param drawerContainerColor container color to be used for the drawer container
- * @param drawerContentColor color of the content to use inside the drawer container. Defaults to
- * either the matching content color for [drawerContainerColor], or, if it is not a color from
- * the theme, this will keep the same value set above this Surface.
+ * @param gesturesEnabled whether or not the drawer can be interacted by gestures
+ * @param drawerShape defines the shape of this drawer's container
+ * @param drawerTonalElevation when [drawerContainerColor] is [ColorScheme.surface], a translucent
+ * primary color overlay is applied on top of the container. A higher tonal elevation value will
+ * result in a darker color in light theme and lighter color in dark theme. See also: [Surface].
+ * @param drawerContainerColor the color used for the background of this drawer. Use
+ * [Color.Transparent] to have no color.
+ * @param drawerContentColor the preferred color for content inside this drawer. Defaults to either
+ * the matching content color for [drawerContainerColor], or to the current [LocalContentColor] if
+ * [drawerContainerColor] is not a color from the theme.
  * @param content content of the rest of the UI
  */
 @Composable
@@ -488,15 +492,17 @@
  *
  * @sample androidx.compose.material3.samples.PermanentNavigationDrawerSample
  *
- * @param drawerContent composable that represents content inside the drawer
- * @param modifier optional modifier for the drawer
- * @param drawerShape shape of the drawer container
- * @param drawerTonalElevation Affects the alpha of the color overlay applied on the container color
- * of the drawer container.
- * @param drawerContainerColor container color to be used for the drawer container
- * @param drawerContentColor color of the content to use inside the drawer container. Defaults to
- * either the matching content color for [drawerContainerColor], or, if it is not a color from
- * the theme, this will keep the same value set above this Surface.
+ * @param drawerContent content inside this drawer
+ * @param modifier the [Modifier] to be applied to this drawer
+ * @param drawerShape defines the shape of this drawer's container
+ * @param drawerTonalElevation when [drawerContainerColor] is [ColorScheme.surface], a translucent
+ * primary color overlay is applied on top of the container. A higher tonal elevation value will
+ * result in a darker color in light theme and lighter color in dark theme. See also: [Surface].
+ * @param drawerContainerColor the color used for the background of this drawer. Use
+ * [Color.Transparent] to have no color.
+ * @param drawerContentColor the preferred color for content inside this drawer. Defaults to either
+ * the matching content color for [drawerContainerColor], or to the current [LocalContentColor] if
+ * [drawerContainerColor] is not a color from the theme.
  * @param content content of the rest of the UI
  */
 @ExperimentalMaterial3Api
@@ -539,20 +545,20 @@
 object DrawerDefaults {
 
     /**
-     * Default Elevation for drawer container in the [ModalNavigationDrawer] as specified in
-     * material specs
+     * Default Elevation for drawer container in the [ModalNavigationDrawer] as specified in the
+     * Material specification.
      */
     val ModalDrawerElevation = NavigationDrawerTokens.ModalContainerElevation
 
     /**
-     * Default Elevation for drawer container in the [PermanentNavigationDrawer] as specified in
-     * material specs
+     * Default Elevation for drawer container in the [PermanentNavigationDrawer] as specified in the
+     * Material specification.
      */
     val PermanentDrawerElevation = NavigationDrawerTokens.StandardContainerElevation
 
     /**
      * Default Elevation for drawer container in the [DismissibleNavigationDrawer] as specified in
-     * material specs
+     * the Material specification.
      */
     val DismissibleDrawerElevation = NavigationDrawerTokens.StandardContainerElevation
 
@@ -571,15 +577,15 @@
  *
  * @param label text label for this item
  * @param selected whether this item is selected
- * @param onClick the callback to be invoked when this item is clicked
- * @param modifier optional [Modifier] for this item
+ * @param onClick called when this item is clicked
+ * @param modifier the [Modifier] to be applied to this item
  * @param icon optional icon for this item, typically an [Icon]
  * @param badge optional badge to show on this item from the end side
- * @param colors the various colors used in elements of this item
+ * @param colors [NavigationDrawerItemColors] that will be used to resolve the colors used for this
+ * item in different states. See [NavigationDrawerItemDefaults.colors].
  * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
- * for this item. You can create and pass in your own remembered [MutableInteractionSource] if
- * you want to observe [Interaction]s and customize the appearance / behavior of this item in
- * different [Interaction]s.
+ * for this item. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this item in different states.
  */
 @Composable
 @ExperimentalMaterial3Api
@@ -630,7 +636,6 @@
 @Stable
 @ExperimentalMaterial3Api
 interface NavigationDrawerItemColors {
-
     /**
      * Represents the icon color for this item, depending on whether it is [selected].
      *
@@ -667,7 +672,6 @@
 /** Defaults used in [NavigationDrawerItem]. */
 @ExperimentalMaterial3Api
 object NavigationDrawerItemDefaults {
-
     /**
      * Creates a [NavigationDrawerItemColors] with the provided colors according to the Material
      * specification.
@@ -706,7 +710,8 @@
     )
 
     /**
-     * Default external padding for a [NavigationDrawerItem] according to material spec.
+     * Default external padding for a [NavigationDrawerItem] according to the Material
+     * specification.
      */
     val ItemPadding = PaddingValues(horizontal = 12.dp)
 }

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/NavigationRail.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/NavigationRail.kt
index 69875b3..af24fb2 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/NavigationRail.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/NavigationRail.kt

@@ -65,9 +65,9 @@
  *
  * ![Navigation rail image](https://developer.android.com/images/reference/androidx/compose/material3/navigation-rail.png)
  *
- * The navigation rail should be used to display three to seven app destinations and,
- * optionally, a Floating Action Button or a logo header. Each destination is typically represented
- * by an icon and an optional text label.
+ * The navigation rail should be used to display three to seven app destinations and, optionally, a
+ * [FloatingActionButton] or a logo header. Each destination is typically represented by an icon and
+ * an optional text label.
  *
  * [NavigationRail] should contain multiple [NavigationRailItem]s, each representing a singular
  * destination.
@@ -78,14 +78,14 @@
  * See [NavigationRailItem] for configuration specific to each item, and not the overall
  * NavigationRail component.
  *
- * @param modifier optional [Modifier] for this NavigationRail
- * @param containerColor the container color for this NavigationRail
- * @param contentColor the preferred content color provided by this NavigationRail to its children.
- * Defaults to either the matching content color for [containerColor], or if [containerColor] is not
- * a color from the theme, this will keep the same value set above this NavigationRail
- * @param header optional header that may hold a Floating Action Button or a logo
- * @param content destinations inside this NavigationRail. This should contain multiple
- * [NavigationRailItem]s
+ * @param modifier the [Modifier] to be applied to this navigation rail
+ * @param containerColor the color used for the background of this navigation rail. Use
+ * [Color.Transparent] to have no color.
+ * @param contentColor the preferred color for content inside this navigation rail. Defaults to
+ * either the matching content color for [containerColor], or to the current [LocalContentColor] if
+ * [containerColor] is not a color from the theme.
+ * @param header optional header that may hold a [FloatingActionButton] or a logo
+ * @param content the content of this navigation rail, typically 3-7 [NavigationRailItem]s
  */
 @Composable
 fun NavigationRail(
@@ -129,19 +129,20 @@
  * is controlled by [alwaysShowLabel].
  *
  * @param selected whether this item is selected
- * @param onClick the callback to be invoked when this item is selected
+ * @param onClick called when this item is clicked
  * @param icon icon for this item, typically an [Icon]
- * @param modifier optional [Modifier] for this item
- * @param enabled controls the enabled state of this item. When false, this item will not be
- * clickable and will appear disabled to accessibility services
+ * @param modifier the [Modifier] to be applied to this item
+ * @param enabled controls the enabled state of this item. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
  * @param label optional text label for this item
  * @param alwaysShowLabel whether to always show the label for this item. If false, the label will
  * only be shown when this item is selected.
  * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
- * for this NavigationRailItem. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the appearance /
- * behavior of this NavigationRailItem in different [Interaction]s.
- * @param colors the various colors used in elements of this item
+ * for this item. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this item in different states.
+ * @param colors [NavigationRailItemColors] that will be used to resolve the colors used for this
+ * item in different states. See [NavigationRailItemDefaults.colors].
  */
 @Composable
 fun NavigationRailItem(

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/OutlinedTextField.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/OutlinedTextField.kt
index 4d10c95..8188c49 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/OutlinedTextField.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/OutlinedTextField.kt

@@ -84,14 +84,14 @@
  * @param value the input text to be shown in the text field
  * @param onValueChange the callback that is triggered when the input service updates the text. An
  * updated text comes as a parameter of the callback
- * @param modifier a [Modifier] for this text field
- * @param enabled controls the enabled state of the [OutlinedTextField]. When `false`, the text
- * field will be neither editable nor focusable, the input of the text field will not be selectable,
- * visually text field will appear in the disabled UI state
- * @param readOnly controls the editable state of the [OutlinedTextField]. When `true`, the text
- * field can not be modified, however, a user can focus it and copy text from it. Read-only text
- * fields are usually used to display pre-filled forms that user can not edit
- * @param textStyle the style to be applied to the input text. Defaults to [LocalTextStyle]
+ * @param modifier the [Modifier] to be applied to this text field
+ * @param enabled controls the enabled state of this text field. When `false`, this component will
+ * not respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param readOnly controls the editable state of the text field. When `true`, the text field cannot
+ * be modified. However, a user can focus it and copy text from it. Read-only text fields are
+ * usually used to display pre-filled forms that a user cannot edit.
+ * @param textStyle the style to be applied to the input text. Defaults to [LocalTextStyle].
  * @param label the optional label to be displayed inside the text field container. The default
  * text style for internal [Text] is [Typography.bodySmall] when the text field is in focus and
  * [Typography.bodyLarge] when the text field is not in focus
@@ -106,28 +106,25 @@
  * @param visualTransformation transforms the visual representation of the input [value]
  * For example, you can use
  * [PasswordVisualTransformation][androidx.compose.ui.text.input.PasswordVisualTransformation] to
- * create a password text field. By default no visual transformation is applied
+ * create a password text field. By default, no visual transformation is applied.
  * @param keyboardOptions software keyboard options that contains configuration such as
  * [KeyboardType] and [ImeAction]
  * @param keyboardActions when the input service emits an IME action, the corresponding callback
  * is called. Note that this IME action may be different from what you specified in
  * [KeyboardOptions.imeAction]
- * @param singleLine when set to true, this text field becomes a single horizontally scrolling
- * text field instead of wrapping onto multiple lines. The keyboard will be informed to not show
- * the return key as the [ImeAction]. Note that [maxLines] parameter will be ignored as the
- * maxLines attribute will be automatically set to 1
+ * @param singleLine when `true`, this text field becomes a single horizontally scrolling text field
+ * instead of wrapping onto multiple lines. The keyboard will be informed to not show the return key
+ * as the [ImeAction]. Note that [maxLines] parameter will be ignored as the maxLines attribute will
+ * be automatically set to 1.
  * @param maxLines the maximum height in terms of maximum number of visible lines. Should be
  * equal or greater than 1. Note that this parameter will be ignored and instead maxLines will be
- * set to 1 if [singleLine] is set to true
- * [KeyboardOptions.imeAction] field.
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this OutlinedTextField. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this OutlinedTextField in different [Interaction]s.
- * @param shape the shape of the text field's border
- * @param colors [TextFieldColors] that will be used to resolve color of the text and content
- * (including label, placeholder, leading and trailing icons, border) for this text field in
- * different states. See [TextFieldDefaults.outlinedTextFieldColors]
+ * set to 1 if [singleLine] is set to true.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this text field. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this text field in different states.
+ * @param shape defines the shape of this text field's border
+ * @param colors [TextFieldColors] that will be used to resolve the colors used for this text field
+ * in different states. See [TextFieldDefaults.outlinedTextFieldColors].
  */
 @Composable
 fun OutlinedTextField(
@@ -229,14 +226,14 @@
  * @param value the input [TextFieldValue] to be shown in the text field
  * @param onValueChange the callback that is triggered when the input service updates values in
  * [TextFieldValue]. An updated [TextFieldValue] comes as a parameter of the callback
- * @param modifier a [Modifier] for this text field
- * @param enabled controls the enabled state of the [OutlinedTextField]. When `false`, the text
- * field will be neither editable nor focusable, the input of the text field will not be selectable,
- * visually text field will appear in the disabled UI state
- * @param readOnly controls the editable state of the [OutlinedTextField]. When `true`, the text
- * field can not be modified, however, a user can focus it and copy text from it. Read-only text
- * fields are usually used to display pre-filled forms that user can not edit
- * @param textStyle the style to be applied to the input text. Defaults to [LocalTextStyle]
+ * @param modifier the [Modifier] to be applied to this text field
+ * @param enabled controls the enabled state of this text field. When `false`, this component will
+ * not respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param readOnly controls the editable state of the text field. When `true`, the text field cannot
+ * be modified. However, a user can focus it and copy text from it. Read-only text fields are
+ * usually used to display pre-filled forms that a user cannot edit.
+ * @param textStyle the style to be applied to the input text. Defaults to [LocalTextStyle].
  * @param label the optional label to be displayed inside the text field container. The default
  * text style for internal [Text] is [Typography.bodySmall] when the text field is in focus and
  * [Typography.bodyLarge] when the text field is not in focus
@@ -251,27 +248,25 @@
  * @param visualTransformation transforms the visual representation of the input [value]
  * For example, you can use
  * [PasswordVisualTransformation][androidx.compose.ui.text.input.PasswordVisualTransformation] to
- * create a password text field. By default no visual transformation is applied
+ * create a password text field. By default, no visual transformation is applied.
  * @param keyboardOptions software keyboard options that contains configuration such as
  * [KeyboardType] and [ImeAction]
  * @param keyboardActions when the input service emits an IME action, the corresponding callback
  * is called. Note that this IME action may be different from what you specified in
  * [KeyboardOptions.imeAction]
- * @param singleLine when set to true, this text field becomes a single horizontally scrolling
- * text field instead of wrapping onto multiple lines. The keyboard will be informed to not show
- * the return key as the [ImeAction]. Note that [maxLines] parameter will be ignored as the
- * maxLines attribute will be automatically set to 1
+ * @param singleLine when `true`, this text field becomes a single horizontally scrolling text field
+ * instead of wrapping onto multiple lines. The keyboard will be informed to not show the return key
+ * as the [ImeAction]. Note that [maxLines] parameter will be ignored as the maxLines attribute will
+ * be automatically set to 1.
  * @param maxLines the maximum height in terms of maximum number of visible lines. Should be
  * equal or greater than 1. Note that this parameter will be ignored and instead maxLines will be
- * set to 1 if [singleLine] is set to true
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this OutlinedTextField. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this OutlinedTextField in different [Interaction]s.
- * @param shape the shape of the text field's border
- * @param colors [TextFieldColors] that will be used to resolve color of the text and content
- * (including label, placeholder, leading and trailing icons, border) for this text field in
- * different states. See [TextFieldDefaults.outlinedTextFieldColors]
+ * set to 1 if [singleLine] is set to true.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this text field. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this text field in different states.
+ * @param shape defines the shape of this text field's border
+ * @param colors [TextFieldColors] that will be used to resolve the colors used for this text field
+ * in different states. See [TextFieldDefaults.outlinedTextFieldColors].
  */
 @Composable
 fun OutlinedTextField(
@@ -647,8 +642,7 @@
 }
 
 /**
- * Calculate the width of the [OutlinedTextField] given all elements that should be
- * placed inside
+ * Calculate the width of the [OutlinedTextField] given all elements that should be placed inside.
  */
 private fun calculateWidth(
     leadingPlaceableWidth: Int,
@@ -669,8 +663,7 @@
 }
 
 /**
- * Calculate the height of the [OutlinedTextField] given all elements that should be
- * placed inside
+ * Calculate the height of the [OutlinedTextField] given all elements that should be placed inside.
  */
 private fun calculateHeight(
     leadingPlaceableHeight: Int,

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/ProgressIndicator.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/ProgressIndicator.kt
index 8959a2f69..35c8eb6 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/ProgressIndicator.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/ProgressIndicator.kt

@@ -62,12 +62,12 @@
  *
  * @sample androidx.compose.material3.samples.LinearProgressIndicatorSample
  *
- * @param progress The progress of this progress indicator, where 0.0 represents no progress and 1.0
+ * @param progress the progress of this progress indicator, where 0.0 represents no progress and 1.0
  * represents full progress. Values outside of this range are coerced into the range.
- * @param modifier The modifier of the progress indicator.
- * @param color The color of the progress indicator.
- * @param trackColor The color of the track behind the indicator, visible when the progress has not
- * reached the area of the overall indicator yet.
+ * @param modifier the [Modifier] to be applied to this progress indicator
+ * @param color color of this progress indicator
+ * @param trackColor color of the track behind the indicator, visible when the progress has not
+ * reached the area of the overall indicator yet
  */
 @Composable
 fun LinearProgressIndicator(
@@ -95,10 +95,10 @@
  *
  * ![Linear progress indicator image](https://developer.android.com/images/reference/androidx/compose/material3/linear-progress-indicator.png)
  *
- * @param modifier The modifier of the progress indicator.
- * @param color The color of the progress indicator.
- * @param trackColor The color of the track behind the indicator, visible when the progress has not
- * reached the area of the overall indicator yet.
+ * @param modifier the [Modifier] to be applied to this progress indicator
+ * @param color color of this progress indicator
+ * @param trackColor color of the track behind the indicator, visible when the progress has not
+ * reached the area of the overall indicator yet
  */
 @Composable
 fun LinearProgressIndicator(
@@ -218,11 +218,11 @@
  *
  * @sample androidx.compose.material3.samples.CircularProgressIndicatorSample
  *
- * @param progress The progress of this progress indicator, where 0.0 represents no progress and 1.0
+ * @param progress the progress of this progress indicator, where 0.0 represents no progress and 1.0
  * represents full progress. Values outside of this range are coerced into the range.
- * @param modifier The modifier of the progress indicator.
- * @param color The color of the progress indicator.
- * @param strokeWidth The stroke width for the progress indicator.
+ * @param modifier the [Modifier] to be applied to this progress indicator
+ * @param color color of this progress indicator
+ * @param strokeWidth stroke width of this progress indicator
  */
 @Composable
 fun CircularProgressIndicator(
@@ -254,9 +254,9 @@
  *
  * ![Circular progress indicator image](https://developer.android.com/images/reference/androidx/compose/material3/circular-progress-indicator.png)
  *
- * @param modifier The modifier of the progress indicator.
- * @param color The color of the progress indicator.
- * @param strokeWidth The stroke width for the progress indicator.
+ * @param modifier the [Modifier] to be applied to this progress indicator
+ * @param color color of this progress indicator
+ * @param strokeWidth stroke width of this progress indicator
  */
 @Composable
 fun CircularProgressIndicator(

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/RadioButton.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/RadioButton.kt
index 6ceb800..4070501 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/RadioButton.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/RadioButton.kt

@@ -58,17 +58,17 @@
  * @sample androidx.compose.material3.samples.RadioGroupSample
  *
  * @param selected whether this radio button is selected or not
- * @param onClick callback to be invoked when the RadioButton is clicked. If null, then this
- * RadioButton will not handle input events, and only act as a visual indicator of [selected] state
- * @param modifier Modifier to be applied to the radio button
- * @param enabled Controls the enabled state of the [RadioButton]. When `false`, this button will
- * not be selectable and appears disabled
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this RadioButton. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this RadioButton in different [Interaction]s.
- * @param colors [RadioButtonColors] that will be used to resolve the color used for this
- * RadioButton in different states. See [RadioButtonDefaults.colors].
+ * @param onClick called when this radio button is clicked. If `null`, then this radio button will
+ * not be interactable, unless something else handles its input events and updates its state.
+ * @param modifier the [Modifier] to be applied to this radio button
+ * @param enabled controls the enabled state of this radio button. When `false`, this component will
+ * not respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this radio button. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this radio button in different states.
+ * @param colors [RadioButtonColors] that will be used to resolve the color used for this radio
+ * button in different states. See [RadioButtonDefaults.colors].
  */
 @ExperimentalMaterial3Api
 @Composable

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Scaffold.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Scaffold.kt
index f8446cc..24e3088 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Scaffold.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Scaffold.kt

@@ -44,22 +44,21 @@
  *
  * @sample androidx.compose.material3.samples.ScaffoldWithSimpleSnackbar
  *
- * @param modifier optional Modifier for the root of the [Scaffold].
- * @param topBar top app bar of the screen. Consider using [SmallTopAppBar].
- * @param bottomBar bottom bar of the screen. Consider using [NavigationBar].
+ * @param modifier the [Modifier] to be applied to this scaffold
+ * @param topBar top app bar of the screen, typically a [SmallTopAppBar]
+ * @param bottomBar bottom bar of the screen, typically a [NavigationBar]
  * @param snackbarHost component to host [Snackbar]s that are pushed to be shown via
- * [SnackbarHostState.showSnackbar]. Usually it's a [SnackbarHost].
- * @param floatingActionButton Main action button of your screen. Consider using
- * [FloatingActionButton] for this slot.
- * @param floatingActionButtonPosition position of the FAB on the screen. See [FabPosition] for
- * possible options available.
- * @param containerColor background of the scaffold body
- * @param contentColor color of the content in scaffold body. Defaults to either the matching
- * content color for [containerColor], or, if it is not a color from the theme, this will keep
- * the same value set above this Surface.
- * @param content content of your screen. The lambda receives an [PaddingValues] that should be
- * applied to the content root via Modifier.padding to properly offset top and bottom bars. If
- * you're using Modifier.VerticalScroll, apply this modifier to the child of the scroll, and not on
+ * [SnackbarHostState.showSnackbar], typically a [SnackbarHost]
+ * @param floatingActionButton Main action button of the screen, typically a [FloatingActionButton]
+ * @param floatingActionButtonPosition position of the FAB on the screen. See [FabPosition].
+ * @param containerColor the color used for the background of this scaffold. Use [Color.Transparent]
+ * to have no color.
+ * @param contentColor the preferred color for content inside this scaffold. Defaults to either the
+ * matching content color for [containerColor], or to the current [LocalContentColor] if
+ * [containerColor] is not a color from the theme.
+ * @param content content of the screen. The lambda receives a [PaddingValues] that should be
+ * applied to the content root via [Modifier.padding] to properly offset top and bottom bars. If
+ * using [Modifier.verticalScroll], apply this modifier to the child of the scroll, and not on
  * the scroll itself.
  */
 @ExperimentalMaterial3Api

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Slider.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Slider.kt
index a99ed4b..5e45d65 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Slider.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Slider.kt

@@ -120,25 +120,26 @@
  *
  * @sample androidx.compose.material3.samples.StepsSliderSample
  *
- * @param value current value of the Slider. If outside of [valueRange] provided, value will be
+ * @param value current value of the slider. If outside of [valueRange] provided, value will be
  * coerced to this range.
- * @param onValueChange lambda in which value should be updated
- * @param modifier modifiers for the Slider layout
- * @param enabled whether or not component is enabled and can be interacted with or not
- * @param valueRange range of values that Slider value can take. Passed [value] will be coerced to
- * this range
- * @param steps if greater than 0, specifies the amounts of discrete values, evenly distributed
- * between across the whole value range. If 0, slider will behave as a continuous slider and allow
- * to choose any value from the range specified. Must not be negative.
- * @param onValueChangeFinished lambda to be invoked when value change has ended. This callback
- * shouldn't be used to update the slider value (use [onValueChange] for that), but rather to
- * know when the user has completed selecting a new value by ending a drag or a click.
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this Slider. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this Slider in different [Interaction]s.
- * @param colors [SliderColors] that will be used to determine the color of the Slider parts in
- * different state. See [SliderDefaults.colors] to customize.
+ * @param onValueChange callback in which value should be updated
+ * @param modifier the [Modifier] to be applied to this slider
+ * @param enabled controls the enabled state of this slider. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param valueRange range of values that this slider can take. The passed [value] will be coerced
+ * to this range.
+ * @param steps if greater than 0, specifies the amount of discrete allowable values, evenly
+ * distributed across the whole value range. If 0, the slider will behave continuously and allow any
+ * value from the range specified. Must not be negative.
+ * @param onValueChangeFinished called when value change has ended. This should not be used to
+ * update the slider value (use [onValueChange] instead), but rather to know when the user has
+ * completed selecting a new value by ending a drag or a click.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this slider. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this slider in different states.
+ * @param colors [SliderColors] that will be used to resolve the colors used for this slider in
+ * different states. See [SliderDefaults.colors].
  */
 // TODO(b/229979132): Add m.io link
 @Composable
@@ -511,7 +512,7 @@
      *
      * For the name references below the words "active" and "inactive" are used. Active part of
      * the slider is filled with progress, so if slider's progress is 30% out of 100%, left (or
-     * right in RTL) 30% of the track will be active, the rest is not active.
+     * right in RTL) 30% of the track will be active, while the rest is inactive.
      *
      * @param thumbColor thumb color when enabled
      * @param disabledThumbColor thumb colors when disabled
@@ -583,7 +584,7 @@
 interface SliderColors {
 
     /**
-     * Represents the color used for the sliders's thumb, depending on [enabled].
+     * Represents the color used for the slider's thumb, depending on [enabled].
      *
      * @param enabled whether the [Slider] is enabled or not
      */
@@ -591,10 +592,10 @@
     fun thumbColor(enabled: Boolean): State<Color>
 
     /**
-     * Represents the color used for the sliders's track, depending on [enabled] and [active].
+     * Represents the color used for the slider's track, depending on [enabled] and [active].
      *
      * Active part is filled with progress, so if sliders progress is 30% out of 100%, left (or
-     * right in RTL) 30% of the track will be active, the rest is not active.
+     * right in RTL) 30% of the track will be active, while the rest is inactive.
      *
      * @param enabled whether the [Slider] is enabled or not
      * @param active whether the part of the track is active of not
@@ -603,7 +604,7 @@
     fun trackColor(enabled: Boolean, active: Boolean): State<Color>
 
     /**
-     * Represents the color used for the sliders's tick which is the dot separating steps, if
+     * Represents the color used for the slider's tick which is the dot separating steps, if
      * they are set on the slider, depending on [enabled] and [active].
      *
      * Active tick is the tick that is in the part of the track filled with progress, so if

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Snackbar.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Snackbar.kt
index 7007fd9..16dc463 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Snackbar.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Snackbar.kt

@@ -68,23 +68,23 @@
  * of the [SnackbarHost] to the [Scaffold]:
  * @sample androidx.compose.material3.samples.ScaffoldWithCustomSnackbar
  *
- * @param modifier modifiers for the Snackbar layout
+ * @param modifier the [Modifier] to be applied to this snackbar
  * @param action action / button component to add as an action to the snackbar. Consider using
  * [ColorScheme.inversePrimary] as the color for the action, if you do not have a predefined color
  * you wish to use instead.
  * @param dismissAction action / button component to add as an additional close affordance action
  * when a snackbar is non self-dismissive. Consider using [ColorScheme.inverseOnSurface] as the
  * color for the action, if you do not have a predefined color you wish to use instead.
- * @param actionOnNewLine whether or not action should be put on the separate line. Recommended
- * for action with long action text
- * @param shape defines the Snackbar's shape (as well as its shadow when using `shadowElevation`)
- * @param containerColor background color of the Snackbar
- * @param contentColor the preferred color for content inside this Snackbar. Also see
- * [LocalContentColor] which is used by [Text] and [Icon] by default.
+ * @param actionOnNewLine whether or not action should be put on a separate line. Recommended for
+ * action with long action text.
+ * @param shape defines the shape of this snackbar's container
+ * @param containerColor the color used for the background of this snackbar. Use [Color.Transparent]
+ * to have no color.
+ * @param contentColor the preferred color for content inside this snackbar
  * @param actionContentColor the preferred content color for the optional [action] inside this
- * Snackbar
+ * snackbar
  * @param dismissActionContentColor the preferred content color for the optional [dismissAction]
- * inside this Snackbar
+ * inside this snackbar
  * @param content content to show information about a process that an app has performed or will
  * perform
  */
@@ -178,18 +178,18 @@
  * @sample androidx.compose.material3.samples.ScaffoldWithIndefiniteSnackbar
  *
  * @param snackbarData data about the current snackbar showing via [SnackbarHostState]
- * @param modifier modifiers for the Snackbar layout
- * @param actionOnNewLine whether or not the Snackbar's action should be put on the separate line
- * (recommended for action with long action text)
- * @param shape defines the Snackbar's shape (as well as its shadow when using `shadowElevation`)
- * @param containerColor background color of the Snackbar
- * @param contentColor the preferred color for content inside this Snackbar. Also see
- * [LocalContentColor] which is used by [Text] and [Icon] by default.
- * @param actionColor color of the Snackbar's action
+ * @param modifier the [Modifier] to be applied to this snackbar
+ * @param actionOnNewLine whether or not action should be put on a separate line. Recommended for
+ * action with long action text.
+ * @param shape defines the shape of this snackbar's container
+ * @param containerColor the color used for the background of this snackbar. Use [Color.Transparent]
+ * to have no color.
+ * @param contentColor the preferred color for content inside this snackbar
+ * @param actionColor the color of the snackbar's action
  * @param actionContentColor the preferred content color for the optional action inside this
- * Snackbar. See [SnackbarVisuals.actionLabel].
+ * snackbar. See [SnackbarVisuals.actionLabel].
  * @param dismissActionContentColor the preferred content color for the optional dismiss action
- * inside this Snackbar. See [SnackbarVisuals.withDismissAction].
+ * inside this snackbar. See [SnackbarVisuals.withDismissAction].
  */
 @Composable
 fun Snackbar(

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/SnackbarHost.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/SnackbarHost.kt
index a382877..7562d4bf 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/SnackbarHost.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/SnackbarHost.kt

@@ -49,35 +49,34 @@
 import kotlin.coroutines.resume
 
 /**
- * State of the [SnackbarHost], controls the queue and the current [Snackbar] being shown inside
- * the [SnackbarHost].
+ * State of the [SnackbarHost], which controls the queue and the current [Snackbar] being shown
+ * inside the [SnackbarHost].
  *
- * This state usually [remember]ed and used to provide a [SnackbarHost] to a [Scaffold].
+ * This state is usually [remember]ed and used to provide a [SnackbarHost] to a [Scaffold].
  */
 @Stable
 class SnackbarHostState {
 
     /**
-     * Only one [Snackbar] can be shown at a time.
-     * Since a suspending Mutex is a fair queue, this manages our message queue
-     * and we don't have to maintain one.
+     * Only one [Snackbar] can be shown at a time. Since a suspending Mutex is a fair queue, this
+     * manages our message queue and we don't have to maintain one.
      */
     private val mutex = Mutex()
 
     /**
-     * The current [SnackbarData] being shown by the [SnackbarHost], of `null` if none.
+     * The current [SnackbarData] being shown by the [SnackbarHost], or `null` if none.
      */
     var currentSnackbarData by mutableStateOf<SnackbarData?>(null)
         private set
 
     /**
-     * Shows or queues to be shown a [Snackbar] at the bottom of the [Scaffold] at
-     * which this state is attached and suspends until snackbar is disappeared.
+     * Shows or queues to be shown a [Snackbar] at the bottom of the [Scaffold] to which this state
+     * is attached and suspends until the snackbar has disappeared.
      *
      * [SnackbarHostState] guarantees to show at most one snackbar at a time. If this function is
-     * called while another snackbar is already visible, it will be suspended until this snack
-     * bar is shown and subsequently addressed. If the caller is cancelled, the snackbar will be
-     * removed from display and/or the queue to be displayed.
+     * called while another snackbar is already visible, it will be suspended until this snackbar is
+     * shown and subsequently addressed. If the caller is cancelled, the snackbar will be removed
+     * from display and/or the queue to be displayed.
      *
      * All of this allows for granular control over the snackbar queue from within:
      *
@@ -106,13 +105,13 @@
         showSnackbar(SnackbarVisualsImpl(message, actionLabel, withDismissAction, duration))
 
     /**
-     * Shows or queues to be shown a [Snackbar] at the bottom of the [Scaffold] at
-     * which this state is attached and suspends until snackbar is disappeared.
+     * Shows or queues to be shown a [Snackbar] at the bottom of the [Scaffold] to which this state
+     * is attached and suspends until the snackbar has disappeared.
      *
      * [SnackbarHostState] guarantees to show at most one snackbar at a time. If this function is
-     * called while another snackbar is already visible, it will be suspended until this snack
-     * bar is shown and subsequently addressed. If the caller is cancelled, the snackbar will be
-     * removed from display and/or the queue to be displayed.
+     * called while another snackbar is already visible, it will be suspended until this snackbar is
+     * shown and subsequently addressed. If the caller is cancelled, the snackbar will be removed
+     * from display and/or the queue to be displayed.
      *
      * All of this allows for granular control over the snackbar queue from within:
      *
@@ -198,7 +197,7 @@
 
 /**
  * Host for [Snackbar]s to be used in [Scaffold] to properly show, hide and dismiss items based
- * on material specification and the [hostState].
+ * on Material specification and the [hostState].
  *
  * This component with default parameters comes build-in with [Scaffold], if you need to show a
  * default [Snackbar], use [SnackbarHostState.showSnackbar].
@@ -211,7 +210,7 @@
  * @sample androidx.compose.material3.samples.ScaffoldWithCustomSnackbar
  *
  * @param hostState state of this component to read and show [Snackbar]s accordingly
- * @param modifier optional modifier for this component
+ * @param modifier the [Modifier] to be applied to this component
  * @param snackbar the instance of the [Snackbar] to be shown at the appropriate time with
  * appearance based on the [SnackbarData] provided as a param
  */

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Surface.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Surface.kt
index 03e8a16..8bd40eb 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Surface.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Surface.kt

@@ -59,17 +59,16 @@
  *
  * 3) Background: Surface fills the shape specified by [shape] with the [color]. If [color] is
  * [ColorScheme.surface] a color overlay will be applied. The color of the overlay depends on the
- * [tonalElevation] of this Surface, and the [LocalAbsoluteTonalElevation] set by any
- * parent surfaces. This ensures that a Surface never appears to have a lower elevation overlay than
- * its ancestors, by summing the elevation of all previous Surfaces.
+ * [tonalElevation] of this Surface, and the [LocalAbsoluteTonalElevation] set by any parent
+ * surfaces. This ensures that a Surface never appears to have a lower elevation overlay than its
+ * ancestors, by summing the elevation of all previous Surfaces.
  *
  * 4) Content color: Surface uses [contentColor] to specify a preferred color for the content of
  * this surface - this is used by the [Text] and [Icon] components as a default color.
  *
  * If no [contentColor] is set, this surface will try and match its background color to a color
  * defined in the theme [ColorScheme], and return the corresponding content color. For example, if
- * the
- * [color] of this surface is [ColorScheme.surface], [contentColor] will be set to
+ * the [color] of this surface is [ColorScheme.surface], [contentColor] will be set to
  * [ColorScheme.onSurface]. If [color] is not part of the theme palette, [contentColor] will keep
  * the same value set above this Surface.
  *

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Switch.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Switch.kt
index 1aea950..c1a8a76 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Switch.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Switch.kt

@@ -72,22 +72,21 @@
  *
  * @sample androidx.compose.material3.samples.SwitchWithThumbIconSample
  *
- * @param checked whether or not this component is checked
- * @param onCheckedChange callback to be invoked when Switch is being clicked,
- * therefore the change of checked state is requested.  If null, then this is passive
- * and relies entirely on a higher-level component to control the "checked" state.
- * @param modifier Modifier to be applied to the switch layout
+ * @param checked whether or not this switch is checked
+ * @param onCheckedChange called when this switch is clicked. If `null`, then this switch will not
+ * be interactable, unless something else handles its input events and updates its state.
+ * @param modifier the [Modifier] to be applied to this switch
  * @param thumbContent content that will be drawn inside the thumb, expected to measure
  * [SwitchDefaults.IconSize]
- * @param enabled whether the component is enabled or grayed out
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this Switch. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this Switch in different [Interaction]s.
- * @param colors [SwitchColors] that will be used to determine the color of the thumb, track,
- * and border in different states. See [SwitchDefaults.colors].
+ * @param enabled controls the enabled state of this switch. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this switch. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this switch in different states.
+ * @param colors [SwitchColors] that will be used to resolve the colors used for this switch in
+ * different states. See [SwitchDefaults.colors].
  */
-// TODO: b/223858692 add m.io documentation
 @Composable
 @Suppress("ComposableLambdaParameterNaming", "ComposableLambdaParameterPosition")
 fun Switch(

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Tab.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Tab.kt
index 0fe566f..8c09d52 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Tab.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Tab.kt

@@ -72,16 +72,16 @@
  * that is not opinionated about its content.
  *
  * @param selected whether this tab is selected or not
- * @param onClick the callback to be invoked when this tab is selected
- * @param modifier optional [Modifier] for this tab
- * @param enabled controls the enabled state of this tab. When `false`, this tab will not
- * be clickable and will appear disabled to accessibility services.
+ * @param onClick called when this tab is clicked
+ * @param modifier the [Modifier] to be applied to this tab
+ * @param enabled controls the enabled state of this tab. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
  * @param text the text label displayed in this tab
  * @param icon the icon displayed in this tab
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this Tab. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this Tab in different [Interaction]s.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this tab. You can create and pass in your own `remember`ed instance to observe [Interaction]s
+ * and customize the appearance / behavior of this tab in different states.
  * @param selectedContentColor the color for the content of this tab when selected, and the color
  * of the ripple.
  * @param unselectedContentColor the color for the content of this tab when not selected
@@ -135,16 +135,16 @@
  * example usage.
  *
  * @param selected whether this tab is selected or not
- * @param onClick the callback to be invoked when this tab is selected
+ * @param onClick called when this tab is clicked
  * @param text the text label displayed in this tab
  * @param icon the icon displayed in this tab
- * @param modifier optional [Modifier] for this tab
- * @param enabled controls the enabled state of this tab. When `false`, this tab will not
- * be clickable and will appear disabled to accessibility services.
- * @param interactionSource the [MutableInteractionSource] representing the different [Interaction]s
- * present on this tab. You can create and pass in your own remembered [MutableInteractionSource] if
- * you want to read the [Interaction] and customize the appearance / behavior of this tab
- * in different [Interaction]s.
+ * @param modifier the [Modifier] to be applied to this tab
+ * @param enabled controls the enabled state of this tab. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this tab. You can create and pass in your own `remember`ed instance to observe [Interaction]s
+ * and customize the appearance / behavior of this tab in different states.
  * @param selectedContentColor the color for the content of this tab when selected, and the color
  * of the ripple.
  * @param unselectedContentColor the color for the content of this tab when not selected
@@ -209,14 +209,14 @@
  * @sample androidx.compose.material3.samples.FancyTab
  *
  * @param selected whether this tab is selected or not
- * @param onClick the callback to be invoked when this tab is selected
- * @param modifier optional [Modifier] for this tab
- * @param enabled controls the enabled state of this tab. When `false`, this tab will not
- * be clickable and will appear disabled to accessibility services.
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this Tab. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this Tab in different [Interaction]s.
+ * @param onClick called when this tab is clicked
+ * @param modifier the [Modifier] to be applied to this tab
+ * @param enabled controls the enabled state of this tab. When `false`, this component will not
+ * respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this tab. You can create and pass in your own `remember`ed instance to observe [Interaction]s
+ * and customize the appearance / behavior of this tab in different states.
  * @param selectedContentColor the color for the content of this tab when selected, and the color
  * of the ripple.
  * @param unselectedContentColor the color for the content of this tab when not selected

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/TabRow.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/TabRow.kt
index 42d27f6..7b6da2f 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/TabRow.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/TabRow.kt

@@ -106,22 +106,21 @@
  * @sample androidx.compose.material3.samples.FancyIndicatorContainerTabs
  *
  * @param selectedTabIndex the index of the currently selected tab
- * @param modifier optional [Modifier] for this TabRow
- * @param containerColor The color of the container for the TabRow. Use [Color.Transparent] to have
- * no color.
- * @param contentColor The preferred content color provided by this TabRow to its children.
- * Defaults to either the matching content color for [containerColor], or if [containerColor] is
- * not a color from the theme, this will keep the same value set above this TabRow.
+ * @param modifier the [Modifier] to be applied to this tab row
+ * @param containerColor the color used for the background of this tab row. Use [Color.Transparent]
+ * to have no color.
+ * @param contentColor the preferred color for content inside this tab row. Defaults to either the
+ * matching content color for [containerColor], or to the current [LocalContentColor] if
+ * [containerColor] is not a color from the theme.
  * @param indicator the indicator that represents which tab is currently selected. By default this
- * will be a [TabRowDefaults.Indicator], using a [TabRowDefaults.tabIndicatorOffset]
- * modifier to animate its position. Note that this indicator will be forced to fill up the
- * entire TabRow, so you should use [TabRowDefaults.tabIndicatorOffset] or similar to
- * animate the actual drawn indicator inside this space, and provide an offset from the start.
- * @param divider the divider displayed at the bottom of the TabRow. This provides a layer of
- * separation between the TabRow and the content displayed underneath.
- * @param tabs the tabs inside this TabRow. Typically this will be multiple [Tab]s. Each element
- * inside this lambda will be measured and placed evenly across the TabRow, each taking up equal
- * space.
+ * will be a [TabRowDefaults.Indicator], using a [TabRowDefaults.tabIndicatorOffset] modifier to
+ * animate its position. Note that this indicator will be forced to fill up the entire tab row, so
+ * you should use [TabRowDefaults.tabIndicatorOffset] or similar to animate the actual drawn
+ * indicator inside this space, and provide an offset from the start.
+ * @param divider the divider displayed at the bottom of the tab row. This provides a layer of
+ * separation between the tab row and the content displayed underneath.
+ * @param tabs the tabs inside this tab row. Typically this will be multiple [Tab]s. Each element
+ * inside this lambda will be measured and placed evenly across the row, each taking up equal space.
  */
 @Composable
 fun TabRow(
@@ -194,26 +193,24 @@
  * scrolling, and evenly places its tabs, see [TabRow].
  *
  * @param selectedTabIndex the index of the currently selected tab
- * @param modifier optional [Modifier] for this ScrollableTabRow
- * @param containerColor The background color for the ScrollableTabRow. Use [Color.Transparent] to
- * have no color.
- * @param contentColor The preferred content color provided by this ScrollableTabRow to its
- * children. Defaults to either the matching content color for [containerColor], or if
- * [containerColor] is not a color from the theme, this will keep the same value set above this
- * ScrollableTabRow.
- * @param edgePadding the padding between the starting and ending edge of ScrollableTabRow, and
- * the tabs inside the ScrollableTabRow. This padding helps inform the user that this tab row can
- * be scrolled, unlike a [TabRow].
+ * @param modifier the [Modifier] to be applied to this tab row
+ * @param containerColor the color used for the background of this tab row. Use [Color.Transparent]
+ * to have no color.
+ * @param contentColor the preferred color for content inside this tab row. Defaults to either the
+ * matching content color for [containerColor], or to the current [LocalContentColor] if
+ * [containerColor] is not a color from the theme.
+ * @param edgePadding the padding between the starting and ending edge of the scrollable tab row,
+ * and the tabs inside the row. This padding helps inform the user that this tab row can be
+ * scrolled, unlike a [TabRow].
  * @param indicator the indicator that represents which tab is currently selected. By default this
- * will be a [TabRowDefaults.Indicator], using a [TabRowDefaults.tabIndicatorOffset]
- * modifier to animate its position. Note that this indicator will be forced to fill up the
- * entire ScrollableTabRow, so you should use [TabRowDefaults.tabIndicatorOffset] or similar to
- * animate the actual drawn indicator inside this space, and provide an offset from the start.
- * @param divider the divider displayed at the bottom of the ScrollableTabRow. This provides a layer
- * of separation between the ScrollableTabRow and the content displayed underneath.
- * @param tabs the tabs inside this ScrollableTabRow. Typically this will be multiple [Tab]s. Each
- * element inside this lambda will be measured and placed evenly across the TabRow, each taking
- * up equal space.
+ * will be a [TabRowDefaults.Indicator], using a [TabRowDefaults.tabIndicatorOffset] modifier to
+ * animate its position. Note that this indicator will be forced to fill up the entire tab row, so
+ * you should use [TabRowDefaults.tabIndicatorOffset] or similar to animate the actual drawn
+ * indicator inside this space, and provide an offset from the start.
+ * @param divider the divider displayed at the bottom of the tab row. This provides a layer of
+ * separation between the tab row and the content displayed underneath.
+ * @param tabs the tabs inside this tab row. Typically this will be multiple [Tab]s. Each element
+ * inside this lambda will be measured and placed evenly across the row, each taking up equal space.
  */
 @Composable
 fun ScrollableTabRow(

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Text.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Text.kt
index d12bcd1..f482132 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Text.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/Text.kt

@@ -55,35 +55,35 @@
  * Additionally, for [color], if [color] is not set, and [style] does not have a color, then
  * [LocalContentColor] will be used.
  *
- * @param text The text to be displayed.
- * @param modifier [Modifier] to apply to this layout node.
+ * @param text the text to be displayed
+ * @param modifier the [Modifier] to be applied to this layout node
  * @param color [Color] to apply to the text. If [Color.Unspecified], and [style] has no color set,
  * this will be [LocalContentColor].
- * @param fontSize The size of glyphs to use when painting the text. See [TextStyle.fontSize].
- * @param fontStyle The typeface variant to use when drawing the letters (e.g., italic).
+ * @param fontSize the size of glyphs to use when painting the text. See [TextStyle.fontSize].
+ * @param fontStyle the typeface variant to use when drawing the letters (e.g., italic).
  * See [TextStyle.fontStyle].
- * @param fontWeight The typeface thickness to use when painting the text (e.g., [FontWeight.Bold]).
- * @param fontFamily The font family to be used when rendering the text. See [TextStyle.fontFamily].
- * @param letterSpacing The amount of space to add between each letter.
+ * @param fontWeight the typeface thickness to use when painting the text (e.g., [FontWeight.Bold]).
+ * @param fontFamily the font family to be used when rendering the text. See [TextStyle.fontFamily].
+ * @param letterSpacing the amount of space to add between each letter.
  * See [TextStyle.letterSpacing].
- * @param textDecoration The decorations to paint on the text (e.g., an underline).
+ * @param textDecoration the decorations to paint on the text (e.g., an underline).
  * See [TextStyle.textDecoration].
- * @param textAlign The alignment of the text within the lines of the paragraph.
+ * @param textAlign the alignment of the text within the lines of the paragraph.
  * See [TextStyle.textAlign].
- * @param lineHeight Line height for the [Paragraph] in [TextUnit] unit, e.g. SP or EM.
+ * @param lineHeight line height for the [Paragraph] in [TextUnit] unit, e.g. SP or EM.
  * See [TextStyle.lineHeight].
- * @param overflow How visual overflow should be handled.
- * @param softWrap Whether the text should break at soft line breaks. If false, the glyphs in the
+ * @param overflow how visual overflow should be handled.
+ * @param softWrap whether the text should break at soft line breaks. If false, the glyphs in the
  * text will be positioned as if there was unlimited horizontal space. If [softWrap] is false,
  * [overflow] and TextAlign may have unexpected effects.
- * @param maxLines An optional maximum number of lines for the text to span, wrapping if
+ * @param maxLines an optional maximum number of lines for the text to span, wrapping if
  * necessary. If the text exceeds the given number of lines, it will be truncated according to
  * [overflow] and [softWrap]. If it is not null, then it must be greater than zero.
- * @param onTextLayout Callback that is executed when a new text layout is calculated. A
+ * @param onTextLayout callback that is executed when a new text layout is calculated. A
  * [TextLayoutResult] object that callback provides contains paragraph information, size of the
  * text, baselines and other details. The callback can be used to add additional decoration or
  * functionality to the text. For example, to draw selection around the text.
- * @param style Style configuration for the text such as color, font, line height etc.
+ * @param style style configuration for the text such as color, font, line height etc.
  */
 @Composable
 fun Text(
@@ -154,37 +154,37 @@
  * Additionally, for [color], if [color] is not set, and [style] does not have a color, then
  * [LocalContentColor] will be used.
  *
- * @param text The text to be displayed.
- * @param modifier [Modifier] to apply to this layout node.
+ * @param text the text to be displayed
+ * @param modifier the [Modifier] to be applied to this layout node
  * @param color [Color] to apply to the text. If [Color.Unspecified], and [style] has no color set,
  * this will be [LocalContentColor].
- * @param fontSize The size of glyphs to use when painting the text. See [TextStyle.fontSize].
- * @param fontStyle The typeface variant to use when drawing the letters (e.g., italic).
+ * @param fontSize the size of glyphs to use when painting the text. See [TextStyle.fontSize].
+ * @param fontStyle the typeface variant to use when drawing the letters (e.g., italic).
  * See [TextStyle.fontStyle].
- * @param fontWeight The typeface thickness to use when painting the text (e.g., [FontWeight.Bold]).
- * @param fontFamily The font family to be used when rendering the text. See [TextStyle.fontFamily].
- * @param letterSpacing The amount of space to add between each letter.
+ * @param fontWeight the typeface thickness to use when painting the text (e.g., [FontWeight.Bold]).
+ * @param fontFamily the font family to be used when rendering the text. See [TextStyle.fontFamily].
+ * @param letterSpacing the amount of space to add between each letter.
  * See [TextStyle.letterSpacing].
- * @param textDecoration The decorations to paint on the text (e.g., an underline).
+ * @param textDecoration the decorations to paint on the text (e.g., an underline).
  * See [TextStyle.textDecoration].
- * @param textAlign The alignment of the text within the lines of the paragraph.
+ * @param textAlign the alignment of the text within the lines of the paragraph.
  * See [TextStyle.textAlign].
- * @param lineHeight Line height for the [Paragraph] in [TextUnit] unit, e.g. SP or EM.
+ * @param lineHeight line height for the [Paragraph] in [TextUnit] unit, e.g. SP or EM.
  * See [TextStyle.lineHeight].
- * @param overflow How visual overflow should be handled.
- * @param softWrap Whether the text should break at soft line breaks. If false, the glyphs in the
+ * @param overflow how visual overflow should be handled.
+ * @param softWrap whether the text should break at soft line breaks. If false, the glyphs in the
  * text will be positioned as if there was unlimited horizontal space. If [softWrap] is false,
  * [overflow] and TextAlign may have unexpected effects.
- * @param maxLines An optional maximum number of lines for the text to span, wrapping if
+ * @param maxLines an optional maximum number of lines for the text to span, wrapping if
  * necessary. If the text exceeds the given number of lines, it will be truncated according to
  * [overflow] and [softWrap]. If it is not null, then it must be greater than zero.
- * @param inlineContent A map store composables that replaces certain ranges of the text. It's
- * used to insert composables into text layout. Check [InlineTextContent] for more information.
- * @param onTextLayout Callback that is executed when a new text layout is calculated. A
+ * @param inlineContent a map storing composables that replaces certain ranges of the text, used to
+ * insert composables into text layout. See [InlineTextContent].
+ * @param onTextLayout callback that is executed when a new text layout is calculated. A
  * [TextLayoutResult] object that callback provides contains paragraph information, size of the
  * text, baselines and other details. The callback can be used to add additional decoration or
  * functionality to the text. For example, to draw selection around the text.
- * @param style Style configuration for the text such as color, font, line height etc.
+ * @param style style configuration for the text such as color, font, line height etc.
  */
 @Composable
 fun Text(

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/TextField.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/TextField.kt
index 262b681..883f5ad 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/TextField.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/TextField.kt

@@ -110,14 +110,14 @@
  * @param value the input text to be shown in the text field
  * @param onValueChange the callback that is triggered when the input service updates the text. An
  * updated text comes as a parameter of the callback
- * @param modifier a [Modifier] for this text field
- * @param enabled controls the enabled state of the [TextField]. When `false`, the text field will
- * be neither editable nor focusable, the input of the text field will not be selectable,
- * visually text field will appear in the disabled UI state
- * @param readOnly controls the editable state of the [TextField]. When `true`, the text
- * field can not be modified, however, a user can focus it and copy text from it. Read-only text
- * fields are usually used to display pre-filled forms that user can not edit
- * @param textStyle the style to be applied to the input text. Defaults to [LocalTextStyle]
+ * @param modifier the [Modifier] to be applied to this text field
+ * @param enabled controls the enabled state of this text field. When `false`, this component will
+ * not respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param readOnly controls the editable state of the text field. When `true`, the text field cannot
+ * be modified. However, a user can focus it and copy text from it. Read-only text fields are
+ * usually used to display pre-filled forms that a user cannot edit.
+ * @param textStyle the style to be applied to the input text. Defaults to [LocalTextStyle].
  * @param label the optional label to be displayed inside the text field container. The default
  * text style for internal [Text] is [Typography.bodySmall] when the text field is in focus and
  * [Typography.bodyLarge] when the text field is not in focus
@@ -132,27 +132,25 @@
  * @param visualTransformation transforms the visual representation of the input [value]
  * For example, you can use
  * [PasswordVisualTransformation][androidx.compose.ui.text.input.PasswordVisualTransformation] to
- * create a password text field. By default no visual transformation is applied
+ * create a password text field. By default, no visual transformation is applied.
  * @param keyboardOptions software keyboard options that contains configuration such as
  * [KeyboardType] and [ImeAction].
  * @param keyboardActions when the input service emits an IME action, the corresponding callback
  * is called. Note that this IME action may be different from what you specified in
  * [KeyboardOptions.imeAction].
- * @param singleLine when set to true, this text field becomes a single horizontally scrolling
- * text field instead of wrapping onto multiple lines. The keyboard will be informed to not show
- * the return key as the [ImeAction]. Note that [maxLines] parameter will be ignored as the
- * maxLines attribute will be automatically set to 1.
+ * @param singleLine when `true`, this text field becomes a single horizontally scrolling text field
+ * instead of wrapping onto multiple lines. The keyboard will be informed to not show the return key
+ * as the [ImeAction]. Note that [maxLines] parameter will be ignored as the maxLines attribute will
+ * be automatically set to 1.
  * @param maxLines the maximum height in terms of maximum number of visible lines. Should be
  * equal or greater than 1. Note that this parameter will be ignored and instead maxLines will be
  * set to 1 if [singleLine] is set to true.
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this TextField. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this TextField in different [Interaction]s.
- * @param shape the shape of the text field's container
- * @param colors [TextFieldColors] that will be used to resolve color of the text, content
- * (including label, placeholder, leading and trailing icons, indicator line) and container for
- * this text field in different states. See [TextFieldDefaults.textFieldColors]
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this text field. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this text field in different states.
+ * @param shape defines the shape of this text field's container
+ * @param colors [TextFieldColors] that will be used to resolve the colors used for this text field
+ * in different states. See [TextFieldDefaults.textFieldColors].
  */
 @Composable
 fun TextField(
@@ -244,14 +242,14 @@
  * @param value the input [TextFieldValue] to be shown in the text field
  * @param onValueChange the callback that is triggered when the input service updates values in
  * [TextFieldValue]. An updated [TextFieldValue] comes as a parameter of the callback
- * @param modifier a [Modifier] for this text field
- * @param enabled controls the enabled state of the [TextField]. When `false`, the text field will
- * be neither editable nor focusable, the input of the text field will not be selectable,
- * visually text field will appear in the disabled UI state
- * @param readOnly controls the editable state of the [TextField]. When `true`, the text
- * field can not be modified, however, a user can focus it and copy text from it. Read-only text
- * fields are usually used to display pre-filled forms that user can not edit
- * @param textStyle the style to be applied to the input text. Defaults to [LocalTextStyle]
+ * @param modifier the [Modifier] to be applied to this text field
+ * @param enabled controls the enabled state of this text field. When `false`, this component will
+ * not respond to user input, and it will appear visually disabled and disabled to accessibility
+ * services.
+ * @param readOnly controls the editable state of the text field. When `true`, the text field cannot
+ * be modified. However, a user can focus it and copy text from it. Read-only text fields are
+ * usually used to display pre-filled forms that a user cannot edit.
+ * @param textStyle the style to be applied to the input text. Defaults to [LocalTextStyle].
  * @param label the optional label to be displayed inside the text field container. The default
  * text style for internal [Text] is [Typography.bodySmall] when the text field is in focus and
  * [Typography.bodyLarge] when the text field is not in focus
@@ -266,27 +264,25 @@
  * @param visualTransformation transforms the visual representation of the input [value].
  * For example, you can use
  * [PasswordVisualTransformation][androidx.compose.ui.text.input.PasswordVisualTransformation] to
- * create a password text field. By default no visual transformation is applied
+ * create a password text field. By default, no visual transformation is applied.
  * @param keyboardOptions software keyboard options that contains configuration such as
  * [KeyboardType] and [ImeAction].
  * @param keyboardActions when the input service emits an IME action, the corresponding callback
  * is called. Note that this IME action may be different from what you specified in
  * [KeyboardOptions.imeAction].
- * @param singleLine when set to true, this text field becomes a single horizontally scrolling
- * text field instead of wrapping onto multiple lines. The keyboard will be informed to not show
- * the return key as the [ImeAction]. Note that [maxLines] parameter will be ignored as the
- * maxLines attribute will be automatically set to 1.
+ * @param singleLine when `true`, this text field becomes a single horizontally scrolling text field
+ * instead of wrapping onto multiple lines. The keyboard will be informed to not show the return key
+ * as the [ImeAction]. Note that [maxLines] parameter will be ignored as the maxLines attribute will
+ * be automatically set to 1.
  * @param maxLines the maximum height in terms of maximum number of visible lines. Should be
  * equal or greater than 1. Note that this parameter will be ignored and instead maxLines will be
  * set to 1 if [singleLine] is set to true.
- * @param interactionSource the [MutableInteractionSource] representing the stream of
- * [Interaction]s for this TextField. You can create and pass in your own remembered
- * [MutableInteractionSource] if you want to observe [Interaction]s and customize the
- * appearance / behavior of this TextField in different [Interaction]s.
- * @param shape the shape of the text field's container
- * @param colors [TextFieldColors] that will be used to resolve color of the text, content
- * (including label, placeholder, leading and trailing icons, indicator line) and container for
- * this text field in different states. See [TextFieldDefaults.textFieldColors]
+ * @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
+ * for this text field. You can create and pass in your own `remember`ed instance to observe
+ * [Interaction]s and customize the appearance / behavior of this text field in different states.
+ * @param shape defines the shape of this text field's container
+ * @param colors [TextFieldColors] that will be used to resolve the colors used for this text field
+ * in different states. See [TextFieldDefaults.textFieldColors].
  */
 @Composable
 fun TextField(

diff --git a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/TextFieldDefaults.kt b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/TextFieldDefaults.kt
index c8910bc..29a500f 100644
--- a/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/TextFieldDefaults.kt
+++ b/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/TextFieldDefaults.kt

@@ -305,6 +305,31 @@
     /**
      * Creates a [TextFieldColors] that represents the default input text, container, and content
      * (including label, placeholder, leading and trailing icons) colors used in a [TextField].
+     *
+     * @param textColor the color used for the input text of this text field
+     * @param disabledTextColor the color used for the input text of this text field when disabled
+     * @param containerColor the container color for this text field
+     * @param cursorColor the cursor color for this text field
+     * @param errorCursorColor the cursor color for this text field when in error state
+     * @param focusedIndicatorColor the indicator color for this text field when focused
+     * @param unfocusedIndicatorColor the indicator color for this text field when not focused
+     * @param disabledIndicatorColor the indicator color for this text field when disabled
+     * @param errorIndicatorColor the indicator color for this text field when in error state
+     * @param focusedLeadingIconColor the leading icon color for this text field when focused
+     * @param unfocusedLeadingIconColor the leading icon color for this text field when not focused
+     * @param disabledLeadingIconColor the leading icon color for this text field when disabled
+     * @param errorLeadingIconColor the leading icon color for this text field when in error state
+     * @param focusedTrailingIconColor the trailing icon color for this text field when focused
+     * @param unfocusedTrailingIconColor the trailing icon color for this text field when not
+     * focused
+     * @param disabledTrailingIconColor the trailing icon color for this text field when disabled
+     * @param errorTrailingIconColor the trailing icon color for this text field when in error state
+     * @param focusedLabelColor the label color for this text field when focused
+     * @param unfocusedLabelColor the label color for this text field when not focused
+     * @param disabledLabelColor the label color for this text field when disabled
+     * @param errorLabelColor the label color for this text field when in error state
+     * @param placeholderColor the placeholder color for this text field
+     * @param disabledPlaceholderColor the placeholder color for this text field when disabled
      */
     @Composable
     fun textFieldColors(
@@ -368,6 +393,30 @@
      * Creates a [TextFieldColors] that represents the default input text, container, and content
      * (including label, placeholder, leading and trailing icons) colors used in an
      * [OutlinedTextField].
+     *
+     * @param textColor the color used for the input text of this text field
+     * @param disabledTextColor the color used for the input text of this text field when disabled
+     * @param containerColor the container color for this text field
+     * @param cursorColor the cursor color for this text field
+     * @param errorCursorColor the cursor color for this text field when in error state
+     * @param focusedBorderColor the border color for this text field when focused
+     * @param unfocusedBorderColor the border color for this text field when not focused
+     * @param disabledBorderColor the border color for this text field when disabled
+     * @param errorBorderColor the border color for this text field when in error state
+     * @param focusedLeadingIconColor the leading icon color for this text field when focused
+     * @param unfocusedLeadingIconColor the leading icon color for this text field when not focused
+     * @param disabledLeadingIconColor the leading icon color for this text field when disabled
+     * @param errorLeadingIconColor the leading icon color for this text field when in error state
+     * @param focusedTrailingIconColor the trailing icon color for this text field when focused
+     * @param unfocusedTrailingIconColor the trailing icon color for this text field when not focused
+     * @param disabledTrailingIconColor the trailing icon color for this text field when disabled
+     * @param errorTrailingIconColor the trailing icon color for this text field when in error state
+     * @param focusedLabelColor the label color for this text field when focused
+     * @param unfocusedLabelColor the label color for this text field when not focused
+     * @param disabledLabelColor the label color for this text field when disabled
+     * @param errorLabelColor the label color for this text field when in error state
+     * @param placeholderColor the placeholder color for this text field
+     * @param disabledPlaceholderColor the placeholder color for this text field when disabled
      */
     @Composable
     fun outlinedTextFieldColors(
@@ -445,35 +494,34 @@
      * @param innerTextField input text field that this decoration box wraps. You will pass here a
      * framework-controlled composable parameter "innerTextField" from the decorationBox lambda of
      * the [BasicTextField]
-     * @param enabled controls the enabled state of the [TextField]. When `false`, visually
-     * text field will appear in the disabled UI state. You must also pass the same value to the
-     * [BasicTextField] for it to adjust the behavior accordingly making the text field
-     * non-editable, non-focusable and non-selectable
+     * @param enabled controls the enabled state of the text field. When `false`, this component
+     * will not respond to user input, and it will appear visually disabled and disabled to
+     * accessibility services. You must also pass the same value to the [BasicTextField] for it to
+     * adjust the behavior accordingly.
      * @param singleLine indicates if this is a single line or multi line text field. You must pass
-     * the same value as to [BasicTextField]
+     * the same value as to [BasicTextField].
      * @param visualTransformation transforms the visual representation of the input [value]. You
-     * must pass the same value as to [BasicTextField]
-     * @param interactionSource this is a read-only [InteractionSource] representing the stream of
-     * [Interaction]s for this text field. You first create and pass in your own remembered
-     * [MutableInteractionSource] to the [BasicTextField] for it to dispatch events. And then pass
-     * the same instance to this decoration box for it to observe [Interaction]s and customize the
-     * appearance / behavior in different [Interaction]s
+     * must pass the same value as to [BasicTextField].
+     * @param interactionSource the read-only [InteractionSource] representing the stream of
+     * [Interaction]s for this text field. You must first create and pass in your own `remember`ed
+     * [MutableInteractionSource] instance to the [BasicTextField] for it to dispatch events. And
+     * then pass the same instance to this decoration box to observe [Interaction]s and customize
+     * the appearance / behavior of this text field in different states.
      * @param isError indicates if the text field's current value is in error state. If set to
      * true, the label, bottom indicator and trailing icon by default will be displayed in error
-     * color
+     * color.
      * @param label the optional label to be displayed inside the text field container. The default
      * text style for internal [Text] is [Typography.bodySmall] when the text field is in focus and
-     * [Typography.bodyLarge] when the text field is not in focus
+     * [Typography.bodyLarge] when the text field is not in focus.
      * @param placeholder the optional placeholder to be displayed when the text field is in focus
      * and the input text is empty. The default text style for internal [Text] is
-     * [Typography.bodyLarge]
+     * [Typography.bodyLarge].
      * @param leadingIcon the optional leading icon to be displayed at the beginning of the text
      * field container
      * @param trailingIcon the optional trailing icon to be displayed at the end of the text field
      * container
-     * @param colors [TextFieldColors] that will be used to resolve color of the text and content
-     * (including label, placeholder, leading and trailing icons, bottom indicator) for this text
-     * field in different states. See [TextFieldDefaults.textFieldColors]
+     * @param colors [TextFieldColors] that will be used to resolve the colors used for this text
+     * field in different states. See [TextFieldDefaults.textFieldColors].
      * @param contentPadding the spacing values to apply internally between the internals of text
      * field and the decoration box container. You can use it to implement dense text fields or
      * simply to control horizontal padding. See [TextFieldDefaults.textFieldWithLabelPadding] and
@@ -541,41 +589,40 @@
      * @param innerTextField input text field that this decoration box wraps. You will pass here a
      * framework-controlled composable parameter "innerTextField" from the decorationBox lambda of
      * the [BasicTextField]
-     * @param enabled controls the enabled state of the [OutlinedTextField]. When `false`, visually
-     * text field will appear in the disabled UI state. You must also pass the same value to the
-     * [BasicTextField] for it to adjust the behavior accordingly making the text field
-     * non-editable, non-focusable and non-selectable
+     * @param enabled controls the enabled state of the text field. When `false`, this component
+     * will not respond to user input, and it will appear visually disabled and disabled to
+     * accessibility services. You must also pass the same value to the [BasicTextField] for it to
+     * adjust the behavior accordingly.
      * @param singleLine indicates if this is a single line or multi line text field. You must pass
-     * the same value as to [BasicTextField]
+     * the same value as to [BasicTextField].
      * @param visualTransformation transforms the visual representation of the input [value]. You
-     * must pass the same value as to [BasicTextField]
-     * @param interactionSource this is a read-only [InteractionSource] representing the stream of
-     * [Interaction]s for this text field. You first create and pass in your own remembered
-     * [MutableInteractionSource] to the [BasicTextField] for it to dispatch events. And then pass
-     * the same instance to this decoration box for it to observe [Interaction]s and customize the
-     * appearance / behavior in different [Interaction]s.
+     * must pass the same value as to [BasicTextField].
+     * @param interactionSource the read-only [InteractionSource] representing the stream of
+     * [Interaction]s for this text field. You must first create and pass in your own `remember`ed
+     * [MutableInteractionSource] instance to the [BasicTextField] for it to dispatch events. And
+     * then pass the same instance to this decoration box to observe [Interaction]s and customize
+     * the appearance / behavior of this text field in different states.
      * @param isError indicates if the text field's current value is in error state. If set to
      * true, the label, bottom indicator and trailing icon by default will be displayed in error
-     * color
+     * color.
      * @param label the optional label to be displayed inside the text field container. The default
      * text style for internal [Text] is [Typography.bodySmall] when the text field is in focus and
-     * [Typography.bodyLarge] when the text field is not in focus
+     * [Typography.bodyLarge] when the text field is not in focus.
      * @param placeholder the optional placeholder to be displayed when the text field is in focus
      * and the input text is empty. The default text style for internal [Text] is
-     * [Typography.bodyLarge]
+     * [Typography.bodyLarge].
      * @param leadingIcon the optional leading icon to be displayed at the beginning of the text
      * field container
      * @param trailingIcon the optional trailing icon to be displayed at the end of the text field
      * container
-     * @param colors [TextFieldColors] that will be used to resolve color of the text and content
-     * (including label, placeholder, leading and trailing icons, border) for this text field in
-     * different states. See [TextFieldDefaults.outlinedTextFieldColors]
+     * @param colors [TextFieldColors] that will be used to resolve the colors used for this text
+     * field in different states. See [TextFieldDefaults.outlinedTextFieldColors].
      * @param border the border to be drawn around the text field. The cutout to fit the [label]
      * will be automatically added by the framework. Note that by default the color of the border
      * comes from the [colors].
      * @param contentPadding the spacing values to apply internally between the internals of text
      * field and the decoration box container. You can use it to implement dense text fields or
-     * simply to control horizontal padding. See [TextFieldDefaults.outlinedTextFieldPadding]
+     * simply to control horizontal padding. See [TextFieldDefaults.outlinedTextFieldPadding].
      */
     @Composable
     @ExperimentalMaterial3Api