Merge pull request #658 from Orange-OpenSource/638-documentation-add-…

…tables-to-explain-api-parameters

638 - Documentation - Add API details and improve documentation

changelog.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased](https://github.com/Orange-OpenSource/ods-android/compare/0.16.0...develop)
 
+### Changed
+
+- \[Lib\] Review and update technical documentation ([#638](https://github.com/Orange-OpenSource/ods-android/issues/638))
+
 ### Fixed
 
 - \[App\] Change illustrations alignment for slider and text field components ([#618](https://github.com/Orange-OpenSource/ods-android/issues/618))

docs/_layouts/main.html

@@ -17,6 +17,14 @@
         max-height: 100%;
     }
 
+    h2, h3 {
+        margin-top: 3rem;
+    }
+
+    h4, h5 {
+        margin-top: 2rem;
+    }
+
     #outer {
         width:100%;
         height:100%;

docs/components/AppBarsBottom.md

@@ -4,22 +4,17 @@ title: "App bars: bottom"
 description: A bottom app bar displays navigation and key actions at the bottom of mobile screens.
 ---
 
----
-
-**Page Summary**
+<br>**On this page**
 
 * [Specifications references](#specifications-references)
 * [Accessibility](#accessibility)
-* [Implementation](#implementation)
-* [Component specific tokens](#component-specific-tokens)
 
 ---
 
 ## Specifications references
 
 - [Design System Manager - App bars](https://system.design.orange.com/0c1af118d/p/23e0e6-app-bars/b/620966)
 - [Material Design - App bars: bottom](https://material.io/components/app-bars-bottom)
-- *Technical documentation soon available*
 
 ## Accessibility
 
@@ -33,135 +28,4 @@ action performs. While optional, their use is strongly encouraged.
 
 When using icons for navigation icons, action items and other elements of bottom
 app bars, you should set a content description on them so that screen readers
-like TalkBack are able to announce their purpose or action, if any.
-
-For an overall content description of the bottom app bar, set an
-`android:contentDescription` or use the `setContentDescription` method on the
-`BottomAppBar`.
-
-For the navigation icon, this can be achieved via the
-`app:navigationContentDescription` attribute or
-`setNavigationContentDescription` method.
-
-For action items and items within the overflow menu, the content description
-needs to be set in the menu:
-
-```xml
-<menu>
-    <item
-          android:contentDescription="@string/content_description_one" />
-    <item
-          android:contentDescription="@string/content_description_two" />
-</menu>
-```
-
-## Implementation
-
-Bottom app bars provide access to a bottom navigation drawer and up to four
-actions, including the floating action button.
-
-> **Jetpack Compose implementation**
-
-*Not available yet*
-
-> **XML implementation**
-
-API and source code:
-
-*   `CoordinatorLayout`: [Class definition](https://developer.android.com/reference/androidx/coordinatorlayout/widget/CoordinatorLayout)
-*   `BottomAppBar`: [Class definition](https://developer.android.com/reference/com/google/android/material/bottomappbar/BottomAppBar), [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomappbar/BottomAppBar.java)
-*   `FloatingActionButton`: [Class definition](https://developer.android.com/reference/com/google/android/material/floatingactionbutton/FloatingActionButton), [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingactionbutton/FloatingActionButton.java)
-
-In the layout:
-
-```xml
-<androidx.coordinatorlayout.widget.CoordinatorLayout
-    android:layout_width="match_parent"
-    android:layout_height="match_parent">
-
-    <!-- Note: A RecyclerView can also be used -->
-    <androidx.core.widget.NestedScrollView
-        android:layout_width="match_parent"
-        android:layout_height="match_parent"
-        android:paddingBottom="100dp"
-        android:clipToPadding="false">
-
-        <!-- Scrollable content -->
-
-    </androidx.core.widget.NestedScrollView>
-
-    <com.google.android.material.bottomappbar.BottomAppBar
-        android:id="@+id/bottomAppBar"
-        android:layout_width="match_parent"
-        android:layout_height="wrap_content"
-        android:layout_gravity="bottom"
-        app:navigationIcon="@drawable/ic_menu_24dp"
-        app:menu="@menu/bottom_app_bar"
-        />
-
-    <com.google.android.material.floatingactionbutton.FloatingActionButton
-        android:layout_width="wrap_content"
-        android:layout_height="wrap_content"
-        app:srcCompat="@drawable/ic_add_24dp"
-        app:layout_anchor="@id/bottomAppBar"
-        />
-
-</androidx.coordinatorlayout.widget.CoordinatorLayout>
-```
-
-In `menu/bottom_app_bar.xml`:
-
-```xml
-<menu>
-
-    <item
-        android:id="@+id/search"
-        android:icon="@drawable/ic_search_24dp"
-        android:title="@string/search"
-        android:contentDescription="@string/content_description_search"
-        app:showAsAction="ifRoom"
-        />
-
-    <item
-        android:id="@+id/more"
-        android:title="@string/more"
-        android:contentDescription="@string/content_description_more"
-        app:showAsAction="never"
-        />
-
-</menu>
-```
-
-In menu/navigation icon drawables:
-
-```xml
-<vector
-    android:tint="?attr/colorControlNormal">
-</vector>
-```
-
-In code:
-
-```kotlin
-bottomAppBar.setNavigationOnClickListener {
-    // Handle navigation icon press
-}
-
-bottomAppBar.setOnMenuItemClickListener { menuItem ->
-    when (menuItem.itemId) {
-        R.id.search -> {
-            // Handle search icon press
-            true
-        }
-        R.id.more -> {
-            // Handle more item (inside overflow menu) press
-            true
-        }
-        else -> false
-    }
-}
-```
-
-## Component specific tokens
-
-_Soon available_
+like TalkBack are able to announce their purpose or action, if any.