doc: add documentation for tokens and improve core documentation

core/src/main/java/com/orange/ouds/core/component/OudsBadge.kt

@@ -111,7 +111,7 @@ fun OudsBadge(
  * Badges have five statuses depending on the context of the information they represent.
  * Each status is designed to convey a specific meaning and ensure clarity in communication.
  *
- * This version of the badge displays numerical values (e.g., unread messages, notifications).
+ * This version of the badge displays numerical values (e.g. unread messages, notifications).
  *
  * **A11Y recommendation:** Provide a more explicit `contentDescription` than the count alone by using a semantics Modifier.
  *

core/src/main/java/com/orange/ouds/core/extensions/OudsLightDarkColorTokenExt.kt

@@ -18,6 +18,14 @@ import androidx.compose.ui.graphics.Color
 import com.orange.ouds.core.theme.isOudsInDarkTheme
 import com.orange.ouds.theme.tokens.components.OudsLightDarkColor
 
+/**
+ * Returns the color corresponding to the current theme mode (Light or Dark).
+ *
+ * This extension property checks the current theme state using [isOudsInDarkTheme]
+ * and returns either the [OudsLightDarkColor.dark] or [OudsLightDarkColor.light] value accordingly.
+ *
+ * @return The resolved [Color] for the current theme context.
+ */
 val OudsLightDarkColor.value: Color
     @ReadOnlyComposable
     @Composable

core/src/main/java/com/orange/ouds/core/theme/OudsBorders.kt

@@ -40,14 +40,36 @@ import com.orange.ouds.theme.tokens.semantic.OudsBorderSemanticTokens
 import java.util.Locale
 
 /**
- * @suppress
+ * Holds all the border-related properties defined in the OUDS theme.
+ *
+ * Borders are used to define boundaries around UI elements to materialise the visual hierarchy and improve usability.
+ *
+ * > Design guidelines: [Border tokens documentation](https://r.orange.fr/r/S-ouds-doc-token-border)
+ *
+ * @property width Collection of border width values.
+ * @property radius Collection of border radius values.
+ * @property style Collection of border styles (solid, dashed, etc.).
  */
-data class OudsBorders(
+@ConsistentCopyVisibility
+data class OudsBorders internal constructor(
     val width: Width,
     val radius: Radius,
     val style: Style
 ) {
-    data class Width(
+    /**
+     * Represents the available border widths in OUDS.
+     *
+     * @property none Width of 0 dp, used when no border is visible.
+     * @property default The standard border width used for most cases.
+     * @property thin A thinner border width for subtle separations.
+     * @property medium A medium border width for increased visibility.
+     * @property thick A thick border width for emphasis.
+     * @property thicker A very thick border width for strong emphasis.
+     * @property focus The border width used to indicate focus states.
+     * @property focusInset The width of the inner border (inset) used in focus states to create a double-border effect.
+     */
+    @ConsistentCopyVisibility
+    data class Width internal constructor(
         val none: Dp,
         val default: Dp,
         val thin: Dp,
@@ -58,7 +80,18 @@ data class OudsBorders(
         val focusInset: Dp
     )
 
-    data class Radius(
+    /**
+     * Represents the available border radius in OUDS.
+     *
+     * @property none No radius (0 dp), resulting in square corners.
+     * @property default The standard radius used for most components.
+     * @property small A small radius for subtle rounding.
+     * @property medium A medium radius for noticeable rounding.
+     * @property large A large radius for significantly rounded corners.
+     * @property pill A fully rounded radius.
+     */
+    @ConsistentCopyVisibility
+    data class Radius internal constructor(
         val none: Dp,
         val default: Dp,
         val small: Dp,
@@ -67,7 +100,14 @@ data class OudsBorders(
         val pill: Dp
     )
 
-    data class Style(
+    /**
+     * Represents the available border styles in OUDS.
+     *
+     * @property default The standard border style (usually solid).
+     * @property drag The specific border style used when an element is being dragged (often dashed).
+     */
+    @ConsistentCopyVisibility
+    data class Style internal constructor(
         val default: OudsBorderStyle,
         val drag: OudsBorderStyle
     )
@@ -134,6 +174,8 @@ private fun OudsBorders.fromToken(token: OudsBorderKeyToken.Style): OudsBorderSt
 
 /**
  * Converts an OUDS border radius token to the local border radius value provided by the theme.
+ *
+ * @suppress
  */
 @InternalOudsApi
 val OudsBorderKeyToken.Radius.value: Dp
@@ -143,6 +185,8 @@ val OudsBorderKeyToken.Radius.value: Dp
 
 /**
  * Converts an OUDS border style token to the local [OudsBorderStyle] value provided by the theme.
+ *
+ * @suppress
  */
 @InternalOudsApi
 val OudsBorderKeyToken.Style.value: OudsBorderStyle
@@ -152,6 +196,8 @@ val OudsBorderKeyToken.Style.value: OudsBorderStyle
 
 /**
  * Converts an OUDS border width token to the local border width value provided by the theme.
+ *
+ * @suppress
  */
 @InternalOudsApi
 val OudsBorderKeyToken.Width.value: Dp