[#638] Homogenize documentations

Orange-OpenSource · Oct 13, 2023 · 1b5ee1f · 1b5ee1f
1 parent 3a3e049
commit 1b5ee1f
Show file tree

Hide file tree

Showing 39 changed files with 414 additions and 747 deletions.
diff --git a/docs/components/AppBarsTop.md b/docs/components/AppBarsTop.md
@@ -21,7 +21,6 @@ description: Top app bars display information and actions relating to the curren
 
 - [Design System Manager - App bars](https://system.design.orange.com/0c1af118d/p/23e0e6-app-bars/b/620966)
 - [Material Design - App bars: top](https://material.io/components/app-bars-top/)
-- Technical documentation soon available
 
 ## Accessibility
 
@@ -37,28 +36,29 @@ action performs.
 
 #### Jetpack Compose implementation
 
-Add `OdsTopAppBar` composable to your Scaffold topBar:
+Add `OdsTopAppBar` composable to your Scaffold `topBar`.
+Here is an example of use:
 
 ```kotlin
 OdsTopAppBar(
     title = "Title",
     navigationIcon = OdsTopAppBarNavigationIcon(
         painter = painterResource(id = R.drawable.ic_back),
         contentDescription = "content description",
-        onClick = { /* Do something */ }
+        onClick = { doSomething() }
     ),
     actions = listOf(
         OdsTopAppBarActionButton(
             painter = painterResource(id = R.drawable.ic_share),
             contentDescription = "content description",
-            onClick = { }
+            onClick = { doSomething() }
         ),
         // ...
     ),
     overflowMenuActions = listOf(
         OdsTopAppBarOverflowMenuActionItem(
             text = "Text",
-            onClick = { }
+            onClick = { doSomething() }
         ),
         // ...
     )
@@ -74,7 +74,7 @@ Parameter | Default value | Description
 `navigationIcon: OdsTopAppBarNavigationIcon?` | `null` | Icon to be displayed at the start of the top app bar
 `actions: List<OdsTopAppBarActionButton>` | `emptyList()` | Actions to be displayed at the end of the top app bar. The default layout here is a `Row`, so icons inside will be placed horizontally.
 `overflowMenuActions: List<OdsTopAppBarOverflowMenuActionItem>` | `emptyList()` | Actions to be displayed in the overflow menu
-`elevated: Boolean` | `true` | True to set an elevation to the top app bar (shadow displayed), false otherwise
+`elevated: Boolean` | `true` | Controls the elevation of the top app bar: `true` to set an elevation to the top app bar (a shadow is displayed below), `false` otherwise
 {:.table}
 
 #### XML implementation
@@ -91,28 +91,28 @@ First, you have to add this line in your application `build.gradle.kts` file cau
 implementation("androidx.compose.material3:material3:<version number>")
 ```
 
-Then you can add `OdsLargeTopAppBar` composable to your Scaffold topBar:
+Then you can add `OdsLargeTopAppBar` composable to your Scaffold `topBar`:
 
 ```kotlin
 OdsLargeTopAppBar(
     title = "Title",
     navigationIcon = OdsTopAppBarNavigationIcon(
         painter = painterResource(id = R.drawable.ic_back),
         contentDescription = "content description",
-        onClick = { /* Do something */ }
+        onClick = { doSomething() }
     ),
     actions = listOf(
         OdsTopAppBarActionButton(
             painter = painterResource(id = R.drawable.ic_share),
             contentDescription = "content description",
-            onClick = { }
+            onClick = { doSomething() }
         ),
         // ...
     ),
     overflowMenuActions = listOf(
         OdsTopAppBarOverflowMenuActionItem(
             text = "Text",
-            onClick = { }
+            onClick = { doSomething() }
         ),
         // ...
     ),
@@ -147,12 +147,12 @@ Scaffold(
 
 Parameter | Default value | Description
 -- | -- | --
-`title: String` | | Title to be displayed in the center of the top app bar
-`modifier: Modifier` | `Modifier` |`Modifier` to be applied to the top app bar
-`navigationIcon: OdsTopAppBarNavigationIcon?` | `null` | Icon to be displayed at the start of the top app bar
-`actions: List<OdsTopAppBarActionButton>` | `emptyList()` | Actions to be displayed at the end of the top app bar. The default layout here is a `Row`, so icons inside will be placed horizontally.
-`overflowMenuActions: List<OdsTopAppBarOverflowMenuActionItem>` | `emptyList()` | Actions to be displayed in the overflow menu
-`scrollBehavior: TopAppBarScrollBehavior` | `null` | `TopAppBarScrollBehavior` to be attached to the top app bar
+`title: String` | | Title displayed in the center of the top app bar
+`modifier: Modifier` | `Modifier` |`Modifier` applied to the top app bar
+`navigationIcon: OdsTopAppBarNavigationIcon?` | `null` | Icon displayed at the start of the top app bar
+`actions: List<OdsTopAppBarActionButton>` | `emptyList()` | Actions displayed at the end of the top app bar. The default layout here is a `Row`, so icons inside will be placed horizontally.
+`overflowMenuActions: List<OdsTopAppBarOverflowMenuActionItem>` | `emptyList()` | Actions displayed in the overflow menu
+`scrollBehavior: TopAppBarScrollBehavior` | `null` | `TopAppBarScrollBehavior` attached to the top app bar
 {:.table}
 
 ## Component specific tokens

diff --git a/docs/components/Banners.md b/docs/components/Banners.md
@@ -25,7 +25,6 @@ Only one banner should be shown at a time
 
 - [Design System Manager - Banners](https://system.design.orange.com/0c1af118d/p/19a040-banners/b/497b77)
 - [Material Design - Banners](https://m2.material.io/components/banners)
-- Technical documentation soon available
 
 ## Accessibility
 
@@ -47,27 +46,23 @@ You can use the `OdsBanner` composable like this:
 
 ```kotlin
 OdsBanner(
-    message = "Message displayed in the banner.",
+    message = "Message displayed into the banner.",
     button1Text = "Dismiss",
-    button2Text = "Detail", // Optional
-    image = painterResource(id = R.drawable.placeholder), // Optional
-    imageContentDescription = "", // Optional
-    onButton1Click = {
-        // Do something
-    },
-    onButton2Click = {
-        // Do something
-    }, // Optional
+    button2Text = "Detail",
+    image = painterResource(id = R.drawable.placeholder),
+    imageContentDescription = "",
+    onButton1Click = { doSomething() },
+    onButton2Click = { doSomething() },
 )
 ```
 
 Parameter | Default value | Description
 -- | -- | --
-`message: String` | | Text to be displayed into the banner
-`firstButton: OdsBannerButton` | | Principal button to be displayed in the banner
-`modifier: Modifier` | `Modifier` | `Modifier` to be applied to the banner
-`image: OdsBannerImage?` | `null` | Image to be displayed in the banner in a circle shape
-`secondButton: OdsBannerButton?` | `null` | Secondary button to be displayed in the banner next to the principal one
+`message: String` | | Text displayed into the banner
+`firstButton: OdsBannerButton` | | Principal button displayed in the banner
+`modifier: Modifier` | `Modifier` | `Modifier` applied to the banner
+`image: OdsBannerImage?` | `null` | Image displayed in the banner in a circle shape
+`secondButton: OdsBannerButton?` | `null` | Secondary button displayed into the banner next to the principal one
 {:.table}
 
 ### XML

diff --git a/docs/components/Buttons.md b/docs/components/Buttons.md
@@ -59,9 +59,9 @@ Use the `OdsButton` composable:
 ```kotlin
 OdsButton(
     text = "Contained button",
-    onClick = {},
+    onClick = { doSomething() },
     enabled = true,
-    icon = OdsButtonIcon(painterResource(R.drawable.ic_coffee)) // Optional, line can be removed if you don't need any icon
+    icon = OdsButtonIcon(painterResource(R.drawable.ic_coffee)) // Line can be removed if you don't need any icon
 )
 ```
 
@@ -71,22 +71,22 @@ through the `style` parameter:
 ```kotlin
 OdsButton(
     text = "Positive button",
-    onClick = {},
+    onClick = { doSomething() },
     enabled = true,
-    icon = OdsButtonIcon(painterResource(R.drawable.ic_coffee)), // Optional, line can be removed if you don't need any icon
+    icon = OdsButtonIcon(painterResource(R.drawable.ic_coffee)), // Line can be removed if you don't need any icon
     style = OdsButtonStyle.FunctionalPositive
 )
 ```
 
 Parameter | Default value | Description
 -- | -- | --
-`text: String` | | Text to be displayed into the button
-`onClick: () -> Unit` | | Callback to be called when the button is clicked
-`modifier: Modifier` | `Modifier` | `Modifier` to be applied to the button
-`icon: OdsButtonIcon?` | `null` | Icon to be displayed in the button before the text
+`text: String` | | Text displayed into the button
+`onClick: () -> Unit` | | Callback invoked when the button is clicked
+`modifier: Modifier` | `Modifier` | `Modifier` applied to the button
+`icon: OdsButtonIcon?` | `null` | Icon displayed in the button before the text
 `enabled: Boolean` | `true` | Controls the enabled state of the button. When `false`, this button will not be clickable.
-`style: OdsButtonStyle` | `OdsButtonStyle.Default` | Style to be applied to the button. Set it to `OdsButtonStyle.Primary` for an highlighted button style or use `OdsButtonStyle.FunctionalPositive`/ `OdsButtonStyle.FunctionalNegative` for a functional green/red button style.
-`displaySurface: OdsDisplaySurface` | `OdsDisplaySurface.Default` | `OdsDisplaySurface` to be applied to the button. It allows to force the button display on light or dark surface. By default, the appearance applied is based on the system night mode value.
+`style: OdsButtonStyle` | `OdsButtonStyle.Default` | Style applied to the button. Set it to `OdsButtonStyle.Primary` for an highlighted button style or use `OdsButtonStyle.FunctionalPositive`/ `OdsButtonStyle.FunctionalNegative` for a functional green/red button style.
+`displaySurface: OdsDisplaySurface` | `OdsDisplaySurface.Default` | `OdsDisplaySurface` applied to the button. It allows to force the button display on light or dark surface. By default, the appearance applied is based on the system night mode value.
 {:.table}
 
 #### XML implementation
@@ -107,22 +107,22 @@ Use the `OdsTextButton` composable:
 ```kotlin
 OdsTextButton(
     text = "Text button",
-    onClick = {},
+    onClick = { doSomething() },
     enabled = true,
-    icon = OdsButtonIcon(painterResource(R.drawable.ic_coffee)), // Optional, line can be removed if you don't need any icon
+    icon = OdsButtonIcon(painterResource(R.drawable.ic_coffee)), // Line can be removed if you don't need any icon
     style = OdsTextButtonStyle.Primary
 )
 ```
 
 Parameter | Default value | Description
 -- | -- | --
-`text: String` | | Text to be displayed into the button
-`onClick: () -> Unit` | | Callback to be called when the button is clicked
-`modifier: Modifier` | `Modifier` | `Modifier` to be applied to the button
-`icon: OdsButtonIcon?` | `null` | Icon to be displayed in the button before the text
+`text: String` | | Text displayed into the button
+`onClick: () -> Unit` | | Callback invoked on button click
+`modifier: Modifier` | `Modifier` | `Modifier` applied to the button
+`icon: OdsButtonIcon?` | `null` | Icon displayed in the button before the text
 `enabled: Boolean` | `true` | Controls the enabled state of the button. When `false`, this button will not be clickable.
-`style: OdsTextButtonStyle` | `OdsTextButtonStyle.Default` | Style to be applied to the button. By default `onSurface` color is used for text color. Use `OdsTextButtonStyle.Primary` for an highlighted text color.
-`displaySurface: OdsDisplaySurface` | `OdsDisplaySurface.Default` | `OdsDisplaySurface` to be applied to the button. It allows to force the button display on light or dark surface. By default, the appearance applied is based on the system night mode value.
+`style: OdsTextButtonStyle` | `OdsTextButtonStyle.Default` | Style applied to the button. By default `onSurface` color is used for text color. Use `OdsTextButtonStyle.Primary` for an highlighted text color.
+`displaySurface: OdsDisplaySurface` | `OdsDisplaySurface.Default` | `OdsDisplaySurface` applied to the button. It allows to force the button display on light or dark surface. By default, the appearance applied is based on the system night mode value.
 {:.table}
 
 #### XML implementation
@@ -145,18 +145,18 @@ OdsOutlinedButton(
     text = "Outlined button",
     onClick = {},
     enabled = true,
-    icon = OdsButtonIcon(painterResource(R.drawable.ic_coffee)) // Optional, line can be removed if you don't need any icon
+    icon = OdsButtonIcon(painterResource(R.drawable.ic_coffee)) // Line can be removed if you don't need any icon
 )
 ```
 
 Parameter | Default value | Description
 -- | -- | --
-`text: String` | | Text to be displayed into the button
-`onClick: () -> Unit` | | Callback to be called when the button is clicked
-`modifier: Modifier` | `Modifier` | `Modifier` to be applied to the button
-`icon: OdsButtonIcon?` | `null` | Icon to be displayed in the button before the text
-`enabled: Boolean` | `true` | Controls the enabled state of the button. When `false`, this button will not be clickable.
-`displaySurface: OdsDisplaySurface` | `OdsDisplaySurface.Default` | `OdsDisplaySurface` to be applied to the button. It allows to force the button display on light or dark surface. By default, the appearance applied is based on the system night mode value.
+`text: String` | | Text displayed into the button
+`onClick: () -> Unit` | | Callback invoked on button click
+`modifier: Modifier` | `Modifier` | `Modifier` applied to the button
+`icon: OdsButtonIcon?` | `null` | Icon displayed in the button before the text
+`enabled: Boolean` | `true` | Controls the enabled state of the button. When `false`, the button is not clickable.
+`displaySurface: OdsDisplaySurface` | `OdsDisplaySurface.Default` | `OdsDisplaySurface` applied to the button. It allows to force the button display on light or dark surface. By default, the appearance applied is based on the system night mode value.
 {:.table}
 
 #### XML implementation
@@ -182,20 +182,20 @@ OdsTextToggleButtonsRow(
     ),
     selectedIndex = 0,
     onSelectedIndexChange = {
-        // Do something like changing selectedIndex to refresh composable with new selection
+        doSomething() // Do something like changing selectedIndex to refresh composable with new selection
     },
     sameItemsWeight = false
 )
 ```
 
 Parameter | Default value | Description
 -- | -- | --
-`textToggleButtons: List<OdsTextToggleButtonsRowItem>` | | `OdsTextToggleButtonsRowItem` to be displayed into the toggle group
-`selectedIndex: Int` | | The `textToggleButtons` list index of the selected button
-`onSelectedIndexChange: (Int) -> Unit` | | Callback to be invoked on selection change
-`modifier: Modifier` | `Modifier` | `Modifier` to be applied to the toggle buttons row
+`textToggleButtons: List<OdsTextToggleButtonsRowItem>` | | Items displayed into the toggle group
+`selectedIndex: Int` | | `textToggleButtons` list index of the selected button
+`onSelectedIndexChange: (Int) -> Unit` | | Callback invoked on selection change
+`modifier: Modifier` | `Modifier` | `Modifier` applied to the toggle buttons row
 `sameItemsWeight: Boolean` | `false` | Controls the place occupied by each item. When `true`, same weight of importance will be applied to each item, they will occupy the same width.
-`displaySurface: OdsDisplaySurface` | `OdsDisplaySurface.Default` | `OdsDisplaySurface` to be applied to the button. It allows to force the button display on light or dark surface. By default, the appearance applied is based on the system night mode value.
+`displaySurface: OdsDisplaySurface` | `OdsDisplaySurface.Default` | `OdsDisplaySurface` applied to the button. It allows to force the button display on light or dark surface. By default, the appearance applied is based on the system night mode value.
 {:.table}
 
 #### XML implementation
@@ -219,9 +219,7 @@ OdsIconButton(
         painterResource(id = R.drawable.ic_ui_light_mode),
         stringResource(id = R.string.theme_changer_icon_content_description_light)
     ),
-    onClick = {
-        // Do something
-    },
+    onClick = { doSomething() },
 )
 ```
 
@@ -252,7 +250,7 @@ Use the `OdsIconToggleButton` composable:
 ```kotlin
 OdsIconToggleButton(
     checked = false,
-    onCheckedChange = { },
+    onCheckedChange = { doSomething() },
     uncheckedIcon = OdsIconButtonIcon(
         painterResource(R.drawable.ic_heart_outlined),
         "Add to favorites"
@@ -264,12 +262,12 @@ OdsIconToggleButton(
 Parameter | Default value | Description
 -- | -- | --
 `checked: Boolean` | | Controls the checked state of the button
-`onCheckedChange: (Boolean) -> Unit` | | Callback to be invoked when the button is checked
-`uncheckedIcon: OdsIconButtonIcon` | | Icon to be displayed when the button is unchecked
-`checkedIcon: OdsIconButtonIcon` | | Icon to be displayed when the button is checked
-`modifier: Modifier` | `Modifier` | `Modifier` to be applied to the button
+`onCheckedChange: (Boolean) -> Unit` | | Callback invoked when the button is checked
+`uncheckedIcon: OdsIconButtonIcon` | | Icon displayed when the button is unchecked
+`checkedIcon: OdsIconButtonIcon` | | Icon displayed when the button is checked
+`modifier: Modifier` | `Modifier` | `Modifier` applied to the button
 `enabled: Boolean` | `true` | Controls the enabled state of the button. When `false`, this button will not be clickable.
-`displaySurface: OdsDisplaySurface` | `OdsDisplaySurface.Default` | `OdsDisplaySurface` to be applied to the button. It allows to force the button display on light or dark surface. By default, the appearance applied is based on the system night mode value.
+`displaySurface: OdsDisplaySurface` | `OdsDisplaySurface.Default` | `OdsDisplaySurface` applied to the button. It allows to force the button display on light or dark surface. By default, the appearance applied is based on the system night mode value.
 {:.table}
 
 #### XML implementation
@@ -301,19 +299,19 @@ OdsIconToggleButtonsRow(
     ),
     selectedIndex = 0,
     onSelectedIndexChange = {
-        // Do something like changing selectedIndex to refresh composable with new selection                        
+        doSomething() // Do something like changing selectedIndex to refresh composable with new selection                        
     },
-    displaySurface = displaySurface // Optional
+    displaySurface = displaySurface
 )
 ```
 
 Parameter | Default value | Description
 -- | -- | --
-`icons: List<OdsIconToggleButtonsRowIcon>` | | `OdsIconToggleButtonsRowIcon` list to be displayed into the toggle group
+`icons: List<OdsIconToggleButtonsRowIcon>` | | Icons to be displayed into the toggle group
 `selectedIndex: Int` | | `icons` list index of the selected button
-`onSelectedIndexChange: (Int) -> Unit` | | Callback to be invoked on selection change
-`modifier: Modifier` | `Modifier` | `Modifier` to be applied to the toggle buttons group
-`displaySurface: OdsDisplaySurface` | `OdsDisplaySurface.Default` | `OdsDisplaySurface` to be applied to the button. It allows to force the button display on light or dark surface. By default, the appearance applied is based on the system night mode value.
+`onSelectedIndexChange: (Int) -> Unit` | | Callback invoked on selection change
+`modifier: Modifier` | `Modifier` | `Modifier` applied to the toggle buttons group
+`displaySurface: OdsDisplaySurface` | `OdsDisplaySurface.Default` | `OdsDisplaySurface` applied to the button. It allows to force the button display on light or dark surface. By default, the appearance applied is based on the system night mode value.
 {:.table}
 
 #### XML implementation