Improve existing documentation

Author: paulinea

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/OudsTheme.kt

@@ -22,6 +22,9 @@ import androidx.compose.runtime.compositionLocalOf
 import androidx.compose.runtime.staticCompositionLocalOf
 import androidx.compose.ui.platform.LocalContext
 import com.orange.ouds.core.extensions.isHighContrastModeEnabled
+import com.orange.ouds.core.theme.OudsTheme.Tweak.ForceDark
+import com.orange.ouds.core.theme.OudsTheme.Tweak.ForceLight
+import com.orange.ouds.core.theme.OudsTheme.Tweak.Invert
 import com.orange.ouds.theme.OudsDrawableResources
 import com.orange.ouds.theme.OudsThemeContract
 import com.orange.ouds.theme.OudsThemeSettings
@@ -57,9 +60,11 @@ internal val LocalComponents = staticCompositionLocalOf<OudsComponents> { missin
 object OudsTheme {
 
     /**
-     * Tweak of the current [OudsTheme] which can be passed to [OudsThemeTweak] composable:
-     *   - Invert set theme in dark when app is in light or in light when app is in dark
-     *   - ForceDark and ForceLight force the theme to be in dark or in light
+     * Defines adjustments that can be applied to the current [OudsTheme] via the [OudsThemeTweak] composable.
+     *
+     * @property Invert Inverts the current theme (switches from Light to Dark or Dark to Light).
+     * @property ForceDark Forces the theme to Dark mode, regardless of the system setting.
+     * @property ForceLight Forces the theme to Light mode, regardless of the system setting.
      */
     enum class Tweak {
         Invert, ForceDark, ForceLight
@@ -132,13 +137,15 @@ object OudsTheme {
 }
 
 /**
- * [OudsTheme] is the theme to apply to your screens in a Jetpack Compose application. Use it at the top of
- * your application in replacement of the `MaterialTheme`.
- * Cause OUDS supports multi-theme, you should pass the OUDS supported [theme] used by your application.
+ * Applies the OUDS theme to the composable hierarchy.
  *
- * @param theme Theme to apply to your application. It must implement [OudsThemeContract] (e.g. OrangeTheme, SoshTheme, ...)
- * @param darkThemeEnabled Indicates whether the dark theme is enabled or not.
- * @param content Theme nested content. The provided [theme] will be applied to this content.
+ * Use this at the top of your application instead of `MaterialTheme`.
+ * Since OUDS supports multiple themes, you must provide the specific [theme] implementation
+ * used by your application.
+ *
+ * @param theme The theme configuration to apply. It must implement [OudsThemeContract] (e.g., OrangeTheme, SoshTheme).
+ * @param darkThemeEnabled Controls whether the dark theme is enabled. Defaults to the system setting.
+ * @param content The content to which the theme will be applied.
  */
 @Composable
 fun OudsTheme(
@@ -181,12 +188,12 @@ fun OudsTheme(
 }
 
 /**
- * Tweaks the current OUDS theme and displays given [content] according to the selected [tweak].
+ * Modifies the current OUDS theme configuration and applies it to the given [content].
  *
- * Note: This composable is directly related to [OudsTheme] and MUST be used inside it.
+ * Note: This composable relies on [OudsTheme] and must be nested within it.
  *
- * @param tweak Tweak applied to the current [OudsTheme].
- * @param content Theme tweak nested content. OudsThemeTweak will be applied to this content.
+ * @param tweak The specific adjustment to apply to the current [OudsTheme] (e.g., forcing dark mode).
+ * @param content The content to which the tweaked theme will be applied.
  */
 @Composable
 fun OudsThemeTweak(tweak: OudsTheme.Tweak, content: @Composable () -> Unit) {
@@ -210,12 +217,16 @@ fun OudsThemeTweak(tweak: OudsTheme.Tweak, content: @Composable () -> Unit) {
 }
 
 /**
- * This function is equivalent to [isSystemInDarkTheme] except it takes the OUDS theme setting into account instead of the system one.
+ * Determines if the OUDS theme is currently in dark mode.
+ *
+ * This function is equivalent to [isSystemInDarkTheme], but it respects overrides applied by [OudsThemeTweak].
+ *
+ * The OUDS theme can be inverted or forced to light/dark modes using [OudsThemeTweak].
+ * The value returned by this function reflects these effective changes.
  *
- * The OUDS theme can be inverted or forced to light or dark when calling [OudsThemeTweak] and the value returned by this method reflects that kind of change.
- * If there is no call to [OudsThemeTweak] anywhere in the layout hierarchy, then this function returns the same value as [isSystemInDarkTheme].
+ * If [OudsThemeTweak] is not used in the layout hierarchy, this function returns the same value as [isSystemInDarkTheme].
  *
- * @return `true` if OUDS is considered to be in 'dark theme'.
+ * @return `true` if the effective OUDS theme is dark, `false` otherwise.
  */
 @Composable
 @ReadOnlyComposable

theme-contract/src/main/java/com/orange/ouds/theme/OudsThemeContract.kt

@@ -29,88 +29,94 @@ import com.orange.ouds.theme.tokens.semantic.OudsSpaceSemanticTokens
 /**
  * An interface to create an OUDS supported theme.
  *
- * Any values that are not set will inherit the Orange theme.
+ * Implementations of this interface define the look and feel of the application by providing specific token values
+ * (colors, typography, spacing, etc.). Any values not explicitly set will generally rely on abstract definitions,
+ * but typical implementations should provide full sets of tokens.
  */
 interface OudsThemeContract : Parcelable {
 
     /**
-     * The theme display name.
+     * The display name of the theme (e.g., "Orange", "Sosh").
      */
     val name: String
 
     /**
-     * The theme settings.
+     * The general settings for the theme configuration.
      */
     val settings: OudsThemeSettings
 
     /**
-     * Color semantic tokens values used in the theme.
+     * The collection of semantic color tokens used in the theme.
      */
     val colorTokens: OudsColorSemanticTokens
 
     /**
-     * Material color matching used in the theme.
+     * The mapping of OUDS tokens to standard Material 3 color roles.
+     * This ensures compatibility with standard Material components.
      */
     val materialColorTokens: OudsMaterialColorTokens
 
     /**
-     * Border semantic tokens values used in the theme.
+     * The collection of border-related tokens (width, radius, style) used in the theme.
      */
     val borderTokens: OudsBorderSemanticTokens
 
     /**
-     * Effect semantic tokens values used in the theme.
+     * The collection of visual effect tokens (e.g., blurs) used in the theme.
      */
     val effectTokens: OudsEffectSemanticTokens
 
     /**
-     * Elevation semantic tokens values used in the theme.
+     * The collection of elevation tokens (z-index, shadows) used in the theme.
      */
     val elevationTokens: OudsElevationSemanticTokens
 
     /**
-     * Font family used in the theme.
-     * You can provide your own theme font family `FontFamily(Font(R.font.my_theme_font))`.
+     * The primary font family used in the theme.
+     *
+     * Defaults to [FontFamily.Default] (system font).
+     * You can provide a custom font family, for example: `FontFamily(Font(R.font.my_custom_font))`.
      */
     val fontFamily: FontFamily
         get() = FontFamily.Default
 
     /**
-     * Font semantic tokens values used in the theme.
+     * The collection of typography semantic tokens (font sizes, weights, line heights) used in the theme.
      */
     val fontTokens: OudsFontSemanticTokens
 
     /**
-     * Grid semantic tokens values used in the theme.
+     * The collection of grid layout tokens used in the theme.
      */
     val gridTokens: OudsGridSemanticTokens
 
     /**
-     * Opacity semantic tokens values used in the theme.
+     * The collection of opacity tokens used in the theme.
      */
     val opacityTokens: OudsOpacitySemanticTokens
 
     /**
-     * Size semantic tokens values used in the theme.
+     * The collection of size tokens (icons, constraints) used in the theme.
      */
     val sizeTokens: OudsSizeSemanticTokens
 
     /**
-     * Space semantic tokens values used in the theme.
+     * The collection of spacing tokens (padding, margins, gaps) used in the theme.
      */
     val spaceTokens: OudsSpaceSemanticTokens
 
     /**
-     * Allows customization of OUDS components.
+     * Specific tokens for customizing the internal behavior or style of OUDS components.
      */
     val componentsTokens: OudsComponentsTokens
 
     /**
-     * Allows customization of drawable resources used by OUDS components.
+     * Allows customization of drawable resources used explicitly by OUDS components.
      *
-     * Caution:
+     * **Caution:**
      * To avoid resource conflicts, Android recommends using a prefix or other consistent naming scheme that is unique to the module (or is unique across all project modules).
-     * So, we strongly recommend that you prefix your resources with the name of your theme. For example, if your theme is called "LoremIpsum" you might name your resources as ic_lorem_ipsum_checkbox_selected, ic_lorem_ipsum_chip_tick, etc.
+     * We strongly recommend that you prefix your resources with the theme name.
+     * Example: If your theme is "LoremIpsum", name resources like `ic_lorem_ipsum_checkbox_selected`, `ic_lorem_ipsum_chip_tick`, etc.
      */
     val drawableResources: OudsDrawableResources
 }