docs: update DocC comments and catalog for semantic tokens (#279)

Signed-off-by: Pierre-Yves Lapersonne <pierreyves.lapersonne@orange.com>

OUDS/Core/OUDS/Sources/OUDSTheme/OUDSTheme+SemanticTokens/OUDSTheme+ElevationCompositeSemanticTokens.swift

@@ -16,7 +16,7 @@ import OUDSTokensRaw
 import OUDSTokensSemantic
 
 // [File not generated with the tokenator]
-// WARNING: Not synchronized with the Figjam / Figma by developers team
+// WARNING: Not synchronized anymore with the Figjam / Figma by developers team
 // Create an issue for update https://github.com/Orange-OpenSource/ouds-ios/issues/new?template=token_update.yml
 
 /// Defines basic values common to all themes for `ElevationCompositeSemanticTokens`.

OUDS/Core/OUDS/Sources/OUDSTheme/OUDSTheme+SemanticTokens/OUDSTheme+SizeMultipleSemanticTokens.swift

@@ -18,7 +18,7 @@ import OUDSTokensSemantic
 // swiftlint:disable line_length
 
 // [File not generated by the tokenator]
-// WARNING: Not synchronized with the Figjam / Figma by developers team
+// WARNING: Not synchronized anymore with the Figjam / Figma by developers team
 // Create an issue for update https://github.com/Orange-OpenSource/ouds-ios/issues/new?template=token_update.yml
 
 /// Defines wrapper objects for size semantic tokens (i.e. in the end `DimensionRawToken`).

OUDS/Core/OUDS/Sources/OUDSTheme/OUDSTheme+SemanticTokens/OUDSTheme+SpaceMultipleSemanticTokens.swift

@@ -16,7 +16,7 @@ import OUDSTokensRaw
 import OUDSTokensSemantic
 
 // [File not generated by the tokenator]
-// WARNING: Not synchronized with the Figjam / Figma by developers team
+// WARNING: Not synchronized anymore with the Figjam / Figma by developers team
 // Create an issue for update https://github.com/Orange-OpenSource/ouds-ios/issues/new?template=token_update.yml
 
 /// Defines wrapper objects for space semantic tokens (i.e. in the end `DimensionRawToken`).

OUDS/Core/OUDS/Sources/OUDSTheme/OUDSTheme+SemanticTokens/OUDSTheme+TypographyMultipleSemanticTokens.swift

@@ -16,7 +16,7 @@ import OUDSTokensRaw
 import OUDSTokensSemantic
 
 // [File not generated by the tokenator]
-// WARNING: Not synchronized with the Figjam / Figma by developers team
+// WARNING: Not synchronized anymore with the Figjam / Figma by developers team
 // Create an issue for update https://github.com/Orange-OpenSource/ouds-ios/issues/new?template=token_update.yml
 
 // swiftlint:disable line_length

OUDS/Core/Tokens/RawTokens/Sources/Declarations/ElevationRawTokens.swift

@@ -15,7 +15,7 @@
 /// Values are defined in *ElevationRawTokens+Values.swift* file updated by the tokenator and *ElevationRawTokens+Values.swift* updated manualy by the development team.
 /// `ElevationRawTokens` are tokens to use to define *elevations* , i.e. in the end box shadow effects. These tokens are used to define these effects thanks to several types: the *blur*, the *X offset* and the *Y offset*, all of them being `ElevationRawToken` type.
 /// Combinations of these three values can be defined inside `ElevationCompositeRawToken` i.e. *composite tokens* defining a whil box shadow to use for elevation effect.
-/// 
+///
 /// Primitive types such as `CGFloat` must be used to as to allow to use `@objc` keywords in extensions for overriding.
 /// Such tokens are packed in a _Swift enum_ so as to gather them in one object with the suitable namespace and avoid to have just constants in nothing else
 ///  (i.e. publicly accessible from everywhere). More optimized than _struct_.

OUDS/Core/Tokens/RawTokens/Sources/Values/ElevationRawTokens+Composites.swift

@@ -12,7 +12,7 @@
 //
 
 // [File not generated with the tokenator]
-// WARNING: Not synchronized with the Figjam / Figma by developers team
+// WARNING: Not synchronized anymore with the Figjam / Figma by developers team
 // Create an issue for update https://github.com/Orange-OpenSource/ouds-ios/issues/new?template=token_update.yml
 
 // swiftlint:disable missing_docs

OUDS/Core/Tokens/RawTokens/Sources/Values/GridRawTokens+Values.swift

@@ -13,7 +13,7 @@
 
 // ଘ( ･ω･)_/ﾟ･:*:･｡☆
 // [File to generate with the tokenator]
-// WARNING: Not synchronized with the Figjam / Figma by developers team
+// WARNING: Not synchronized anymore with the Figjam / Figma by developers team
 // Create an issue for update https://github.com/Orange-OpenSource/ouds-ios/issues/new?template=token_update.yml
 
 // swiftlint:disable missing_docs

OUDS/Core/Tokens/RawTokens/Sources/Values/TypographyRawTokens+Composites.swift

@@ -12,7 +12,7 @@
 //
 
 // [File not generated with the tokenator]
-// WARNING: Not synchronized with the Figjam / Figma by developers team
+// WARNING: Not synchronized anymore with the Figjam / Figma by developers team
 // Create an issue for update https://github.com/Orange-OpenSource/ouds-ios/issues/new?template=token_update.yml
 
 // swiftlint:disable missing_docs

OUDS/Core/Tokens/SemanticTokens/Sources/Multiples/MultipleColorTokens.swift

@@ -15,9 +15,29 @@ import OUDSFoundations
 import OUDSTokensRaw
 import SwiftUI
 
-/// Kind of semantic tokens which will wrap a combination of `ColorRawToken` depending to color scheme.
+/// Kind of semantic tokens which will wrap a combination of `ColorSemanticToken` depending to *color scheme* (i.e. ligh mode or dark mode).
 /// Kind of composite token with multiple values, but not named "composite" because this word is already used in the design system.
-/// Allows to gather the multiple-value tokens from Figma inside one object.
+/// Allows to gather the multiple-value tokens from *Figma* inside one object.
+/// If a color token exists with its value depending to the color scheme, it must be packed in such `MultipleColorTokens`
+///
+///         // Assuming in Figma with have a color semantic token colorBgPrimary,
+///         // two semantic color tokens will be defined in Figma and generated by tokenator.
+///         // They can be declared in protocol ColorSemanticTokens,
+///         // and defined automaticaly in OUDSTheme+ColorSemanticTokens extension
+///         var colorBgPrimaryLight: ColorSemanticToken { ColorRawTokens.colorFunctionalWhite }
+///         var colorBgPrimaryDark: ColorSemanticToken { ColorRawTokens.colorFunctionalDarkGray880 }
+///
+///         // Then the develoment team declares an "higher" level color semantic token for colorBgPrimary
+///         // inside ColorMultipleSemanticTokens protocol,
+///         // and defined inside OUDSTheme+ColorMultipleSemanticToken extension
+///         var colorBgPrimary: MultipleColorTokens { MultipleColorTokens(light: colorBgPrimaryLight, dark: colorBgPrimaryDark) }
+///
+///         // If the same color is used whatever the color scheme is
+///         var colorBgPrimary: MultipleColorTokens { MultipleColorTokens(colorBgPrimaryLight) }
+///
+///         // The theme exposes both generated color semantic tokens and "crafted" higher level color semantic tokens.
+///         // It is recommended to use the higher level version as it is less error-prone.
+///
 public final class MultipleColorTokens: NSObject, Sendable {
 
     /// For **light** mode scheme
@@ -26,14 +46,14 @@ public final class MultipleColorTokens: NSObject, Sendable {
     /// For **dark** mode scheme
     public let dark: ColorSemanticToken
 
-    /// Initializes a new color composite semantic token with the same value for light and dark modes
+    /// Initializes a new color multiple semantic token with the same value for light and dark modes
     /// - Parameter value: The `ColorSemanticToken` to apply wether the device is in *light* and *dark* mode
     public init(_ value: ColorSemanticToken) {
         self.light = value
         self.dark = value
     }
 
-    /// Initializes a new color composite semantic token with two values
+    /// Initializes a new color multiple semantic token with two values
     /// - Parameters:
     ///    - light: The `ColorSemanticToken` to apply if device in *light* mode
     ///    - dark: The `ColorSemanticToken` to apply if device in *dark* mode
@@ -53,8 +73,8 @@ public final class MultipleColorTokens: NSObject, Sendable {
     }
 
     /// Returns the right color according to the `colorScheme`.
-    /// - Parameter colorScheme: The color scheme
-    /// - Returns: The right color raw token
+    /// - Parameter colorScheme: The color scheme in use to define the value to use
+    /// - Returns: The `SwiftUI.Color` value to use
     public func color(for colorScheme: ColorScheme) -> Color {
         (colorScheme == .light ? light : dark).color
     }

OUDS/Core/Tokens/SemanticTokens/Sources/Multiples/MultipleElevationTokens.swift

@@ -15,9 +15,30 @@ import OUDSFoundations
 import OUDSTokensRaw
 import SwiftUI
 
-/// Semantic tokens which will wrap a combination of `ElevationCompositeRawToken` depending to color scheme.
+/// Semantic tokens which will wrap a combination of `ElevationCompositeRawToken` depending to color scheme (i.e. light mode or dark mode)
 /// Kind of composite token with multiple values, but not named "composite" because this word is already used in the design system.
-/// Allows to gather the multiple-value tokens from Figma inside one object.
+/// Allows to gather the multiple-value tokens from *Figma* inside one object.
+/// If an elevation token exists with its value depending to the color scheme, it must be packed in such `MultipleElevationTokens`
+///
+///         // Assuming in Figma with have a elevation semantic token elevationNone,
+///         // with values depending to color scheme. These values are defined as elevation raw tokens.
+///         let elevationBottom_0 = ElevationCompositeRawToken(x: elevationX0, y: elevationY0, blur: elevationBlur0, color: ColorRawTokens.colorTransparentBlack0)
+///         let elevationBottom_1_100 = ElevationCompositeRawToken(x: elevationX0, y: elevationY100, blur: elevationBlur200, color: ColorRawTokens.colorTransparentBlack100)
+///
+///         // Then the develoment team declares an "higher" level elevation semantic token
+///         // inside ElevationCompositeSemanticTokens protocol,
+///         // and defined inside OUDSTheme+ElevationCompositeSemanticTokens extension
+///         // ElevationCompositeSemanticToken is a typealias for MultipleElevationTokens to keep same grammar as dsign kit
+///         var elevationNone: ElevationCompositeSemanticToken { ElevationCompositeSemanticToken(light: elevationBottom_0, dark: elevationBottom_1_100) }
+///
+///         // If the same color is used whatever the color scheme is
+///         var elevationNone: ElevationCompositeSemanticToken { ElevationCompositeSemanticToken(elevationBottom_0) }
+///
+///         // The theme exposes both generated elevation semantic tokens and "crafted" higher level elevation semantic tokens.
+///         // It is recommended to use the higher level version as it is less error-prone.
+///
+/// The case of this `MultipleElevationTokens` is quite particular because in fact it contains `ElevationCompositeRawToken` (i.e. raw tokens) instead of semantic tokens.
+/// In fact only the *color* of the elevation effect vary depending to the color scheme, but in the *Figma* kit this is composite raw tokens which are defined for ligh and dark mode as only one token.
 public final class MultipleElevationTokens: NSObject, Sendable {
 
     /// For **light** mode scheme
@@ -54,7 +75,7 @@ public final class MultipleElevationTokens: NSObject, Sendable {
 
     /// Returns the right elevation according to the `colorScheme`.
     /// - Parameter colorScheme: The color scheme
-    /// - Returns: The right elevation raw token
+    /// - Returns: The `ElevationCompositeRawToken` to use depending to `colorScheme`
     public func elevation(for colorScheme: ColorScheme) -> ElevationCompositeRawToken {
         (colorScheme == .light ? light : dark)
     }

OUDS/Core/Tokens/SemanticTokens/Sources/Multiples/MultipleFontLetterSpacingTokens.swift

@@ -15,7 +15,28 @@ import Foundation
 import OUDSTokensRaw
 
 /// Kind of semantic tokens which will wrap a combination of `MultipleFontLetterSpacingTokens` depending to size classes.
-/// Allows to gather the multiple-value tokens from Figma inside one object.
+/// Allows to gather the multiple-value tokens from *Figma* inside one object.
+/// If a font letter spacing token exists with its value depending to the size class (i.e. comapct or regular mode), it must be packed in such `MultipleFontLetterSpacingTokens`
+///
+///         // Assuming in Figma with have a font letter spacing semantic token fontLetterSpacingDisplayMedium,
+///         // two semantic font letter spacing tokens will be defined in Figma and generated by tokenator because
+///         // its value can vary if comapct or regular modes.
+///         // They can be declared in protocol TypographySemanticTokens,
+///         // and defined automaticaly in OUDSTheme+TypographySemanticTokens extension
+///         var fontLetterSpacingDisplayMediumMobile: TypographyFontLetterSpacingSemanticToken { TypographyRawTokens.fontLetterSpacing750 }
+///         var fontLetterSpacingDisplayMediumTablet: TypographyFontLetterSpacingSemanticToken { TypographyRawTokens.fontLetterSpacing1050 }
+///
+///         // Then the develoment team declares an "higher" level font letter spacing semantic token for fontLetterSpacingDisplayMedium
+///         // inside TypographyMultipleSemanticTokens protocol,
+///         // and defined inside OUDSTheme+TypographyMultipleSemanticTokens extension
+///         var fontLetterSpacingDisplayMedium: MultipleFontLetterSpacingTokens { MultipleFontLetterSpacingTokens(compact: fontLetterSpacingDisplayMediumMobile, regular: fontLetterSpacingDisplayMediumTablet) }
+///
+///         // If the same value is used whatever the size class is
+///         var fontLetterSpacingDisplayMedium: MultipleFontLetterSpacingTokens { MultipleFontLetterSpacingTokens(fontLetterSpacingDisplayMediumMobile) }
+///
+///         // The theme exposes both generated font letter spacing semantic tokens and "crafted" higher level color semantic tokens.
+///         // It is recommended to use the higher level version as it is less error-prone.
+///
 public final class MultipleFontLetterSpacingTokens: NSObject, Sendable {
 
     /// For **extra-compact** and **compact** viewports

OUDS/Core/Tokens/SemanticTokens/Sources/Multiples/MultipleFontLineHeightTokens.swift

@@ -15,7 +15,28 @@ import Foundation
 import OUDSTokensRaw
 
 /// Kind of semantic tokens which will wrap a combination of `TypographyFontLineHeightSemanticToken` depending to size classes.
-/// Allows to gather the multiple-value tokens from Figma inside one object.
+/// Allows to gather the multiple-value tokens from *Figma* inside one object.
+/// If a font line height token exists with its value depending to the size class, it must be packed in such `MultipleFontLineHeightTokens`
+///
+///         // Assuming in Figma with have a font letter spacing semantic token fontLineHeightLabelXLarge,
+///         // two semantic font line height spacing tokens will be defined in Figma and generated by tokenator because
+///         // its value can vary if compact or regular modes.
+///         // They can be declared in protocol TypographySemanticTokens,
+///         // and defined automaticaly in OUDSTheme+TypographySemanticTokens extension
+///         var fontLineHeightLabelXLargeMobile: TypographyFontLineHeightSemanticToken { TypographyRawTokens.fontLineHeight450 }
+///         var fontLineHeightLabelXLargeTablet: TypographyFontLineHeightSemanticToken { TypographyRawTokens.fontLineHeight450 }
+///
+///         // Then the develoment team declares an "higher" level line height semantic token for fontLineHeightLabelXLarge
+///         // inside TypographyMultipleSemanticTokens protocol,
+///         // and defined inside OUDSTheme+TypographyMultipleSemanticTokens extension
+///         var fontLineHeightLabelXLarge: MultipleFontLineHeightTokens { MultipleFontLineHeightTokens(compact: fontLineHeightLabelXLargeMobile, regular: fontLineHeightLabelXLargeTablet) }
+///
+///         // If the same value is used whatever the size class is
+///         var fontLineHeightLabelXLarge: MultipleFontLineHeightTokens { MultipleFontLineHeightTokens(fontLineHeightLabelXLargeMobile) }
+///
+///         // The theme exposes both generated font line height semantic tokens and "crafted" higher level color semantic tokens.
+///         // It is recommended to use the higher level version as it is less error-prone.
+///
 public final class MultipleFontLineHeightTokens: NSObject, Sendable {
 
     /// For **extra-compact** and **compact** viewports

OUDS/Core/Tokens/SemanticTokens/Sources/Multiples/MultipleFontSizeTokens.swift

@@ -16,6 +16,27 @@ import OUDSTokensRaw
 
 /// Kind of semantic tokens which will wrap a combination of `TypographyFontSizeSemanticToken` depending to size classes.
 /// Allows to gather the multiple-value tokens from Figma inside one object.
+/// If a font size exists with its value depending to the size class, it must be packed in such `MultipleFontSizeTokens`
+///
+///         // Assuming in Figma with have a font size semantic token fontSizeBodySmall,
+///         // two semantic font size tokens will be defined in Figma and generated by tokenator because
+///         // its value can vary if compact or regular modes.
+///         // They can be declared in protocol TypographySemanticTokens,
+///         // and defined automaticaly in OUDSTheme+TypographySemanticTokens extension
+///         var fontSizeBodySmallMobile: TypographyFontSizeSemanticToken { TypographyRawTokens.fontSize150 }
+///         var fontSizeBodySmallTablet: TypographyFontSizeSemanticToken { TypographyRawTokens.fontSize150 }
+///
+///         // Then the develoment team declares an "higher" level font size semantic token for fontSizeBodySmall
+///         // inside TypographyMultipleSemanticTokens protocol,
+///         // and defined inside OUDSTheme+TypographyMultipleSemanticTokens extension
+///         var fontSizeBodySmall: MultipleFontSizeTokens { MultipleFontSizeTokens(compact: fontSizeBodySmallMobile, regular: fontSizeBodySmallTablet) }
+///
+///         // If the same value is used whatever the size class is
+///         var fontSizeBodySmall: MultipleFontSizeTokens { MultipleFontSizeTokens(fontSizeBodySmallMobile) }
+///
+///         // The theme exposes both generated font size semantic tokens and "crafted" higher level color semantic tokens.
+///         // It is recommended to use the higher level version as it is less error-prone.
+///
 public final class MultipleFontSizeTokens: NSObject, Sendable {
 
     /// For **extra-compact** and **compact** viewports

OUDS/Core/Tokens/SemanticTokens/Sources/Multiples/MultipleSizeTokens.swift

@@ -17,6 +17,27 @@ import SwiftUICore
 /// Kind of semantic tokens which will wrap a combination of `SizeSemanticToken` depending to viewports / size classes.
 /// Kind of composite token with multiple values, but not named "composite" because this word is already used in the design system.
 /// Allows to gather the multiple-value tokens from Figma inside one object.
+/// If a size token exists with its value depending to the size class, it must be packed in such `MultipleSizeTokens`
+///
+///         // Assuming in Figma with have a size semantic token sizeIconWithHeadingXLargeTall,
+///         // two semantic size tokens will be defined in Figma and generated by tokenator because
+///         // its value can vary if compact or regular modes.
+///         // They can be declared in protocol SizeSemanticTokens,
+///         // and defined automaticaly in OUDSTheme+SizeSemanticTokens extension
+///         var sizeIconWithHeadingXLargeTallMobile: SizeSemanticToken { DimensionRawTokens.dimension650 }
+///         var sizeIconWithHeadingXLargeTallTablet: SizeSemanticToken { DimensionRawTokens.dimension800 }
+///
+///         // Then the develoment team declares an "higher" level size semantic token for sizeIconWithHeadingXLargeTall
+///         // inside SizeMultipleSemanticTokens protocol,
+///         // and defined inside OUDSTheme+SizeMultipleSemanticTokens extension
+///         var sizeIconWithHeadingXLargeTall: MultipleSizeTokens { MultipleSizeTokens(compact: sizeIconWithHeadingXLargeTallMobile, regular: sizeIconWithHeadingXLargeTallTablet) }
+///
+///         // If the same value is used whatever the size class is
+///         var sizeIconWithHeadingXLargeTall: MultipleSizeTokens { MultipleSizeTokens(sizeIconWithHeadingXLargeTallTablet) }
+///
+///         // The theme exposes both generated font size semantic tokens and "crafted" higher level color semantic tokens.
+///         // It is recommended to use the higher level version as it is less error-prone.
+///
 public final class MultipleSizeTokens: NSObject, Sendable {
 
     /// For **extra-compact** and **compact** viewports