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

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

OUDS/Core/Tokens/RawTokens/Sources/Composites/ElevationCompositeRawToken.swift

@@ -13,7 +13,10 @@
 
 import Foundation
 
-/// In the global design system, composite tokens are defined for elevation effects.
+/// In the *Figma* global design system, composite tokens are defined for elevation effects.
+/// Composite tokens are tokens defined in *Figma* by other tokens.
+/// Here an *elevation* is caracterized by *x and Y offsets*, a *radius* for the shadow and a *color* to apply on that shadow.
+/// All these elements are *raw tokens*, and together define a *composite raw token* for *elevation* effect.
 /// It is defined as a `final class` and `NSObject` so as to be shared through `@objc` with extensions and protocols within modules.
 public final class ElevationCompositeRawToken: NSObject, Sendable { // NSObject for @objc compatibility
 

OUDS/Core/Tokens/RawTokens/Sources/Composites/TypographyCompositeRawToken.swift

@@ -16,8 +16,10 @@ import OUDSFoundations
 /// An operator to make for example comparisons between `TypographyCompositeRawToken`
 infix operator <|
 
-/// Composite raw tokens are here to pack a set of specific values according to the global design system tool.
-/// Here a *typography* is finaly defined by some specific values.
+/// In the *Figma* global design system, composite tokens are defined for typography-related things.
+/// Composite tokens are tokens defined in *Figma* by other tokens.
+/// Here a *typography* thing is caracterized by a *font size*, a *line height*, a *font weight* and *letter spacig* values.
+/// All these elements are *raw tokens*, and together define a *composite raw token* for *typography* thing.
 public struct TypographyCompositeRawToken: Equatable, Sendable {
 
     // Font family is not included here because this is the only thing which can vary

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

@@ -11,7 +11,9 @@
 // Software description: A SwiftUI components library with code examples for Orange Unified Design System 
 //
 
-/// Defined as the group of all **raw tokens** related to **borders**.
+/// Defines a group of all **raw tokens** related to **borders**.
+/// Values are defined in *BorderRawTokens+Values.swift* file and generated by the tokenator.
+/// `BorderRawTokens` are tokens to use to define *borders* of components. Several types of *raw tokens* exist to render a border: radius (`BorderRadiusRawToken`), style (`BorderStyleRawToken`) and width (`BorderWidthRawToken`).
 ///
 /// Primitive types such as `Double` and `String` must be used to as to allow to use `@objc` keywords in _Swift 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
@@ -20,4 +22,5 @@ public enum BorderRawTokens {
 
     // ଘ( ･ω･)_/ﾟ･:*:･｡☆
     // Note: So as to help the Figma-JSON-to-Swift parser the values have been added in the Values folder
+    // This trick helps also to write documentation for these tokens as the tokenator cannot generate documentation
 }

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

@@ -12,13 +12,18 @@
 //
 
 /// Defined as the group of all **raw tokens** related to **colors**.
+/// Values are defined in *ColorRawTokens+Values.swift* file and generated by the tokenator.
+/// `ColorRawTokens` are tokens to use to define *colors* of components thants to `ColorRawToken` type. Some of these colors are "raw", and others have transparancy effects.
+/// This enum contains also the shared colors, i.e. colors exposed to any theme. Some colors related to the Orange brand are defined elswhere in `OrangeBrandColorRawTokens`.
+///
 /// Primitive types such as  `String` 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_.
 public enum ColorRawTokens {
 
     // ଘ( ･ω･)_/ﾟ･:*:･｡☆
     // Note: So as to help the Figma-JSON-to-Swift parser the values have been added in the Values folder
+    // This trick helps also to write documentation for these tokens as the tokenator cannot generate documentation
 
     /// Applies to a color in its hexadecimal representation the given `opacity`
     /// - Parameters:

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

@@ -12,11 +12,15 @@
 //
 
 /// Defined as the group of all **raw tokens** related to **dimensions**.
+/// Values are defined in *DimensionRawTokens+Values.swift* file and generated by the tokenator.
+/// `DimensionRawTokens` are tokens to use to define *dimensions* , i.e. kind of values to use for sizes or spaces thanks to `DimensionRawToken`.
+/// 
 /// Primitive types such as `Double` 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_.
 public enum DimensionRawTokens {
 
     // ଘ( ･ω･)_/ﾟ･:*:･｡☆
     // Note: So as to help the Figma-JSON-to-Swift parser the values have been added in the Values folder
+    // This trick helps also to write documentation for these tokens as the tokenator cannot generate documentation
 }

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

@@ -12,11 +12,16 @@
 //
 
 /// Defined as the group of all **raw tokens** related to **elevations**.
+/// 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_.
 public enum ElevationRawTokens {
 
     // ଘ( ･ω･)_/ﾟ･:*:･｡☆
     // Note: So as to help the Figma-JSON-to-Swift parser the values have been added in the Values folder
+    // This trick helps also to write documentation for these tokens as the tokenator cannot generate documentation
 }

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

@@ -12,11 +12,15 @@
 //
 
 /// Defined as the group of all **raw tokens** related to **grid**.
+/// Values are defined in *GridRawTokens+Values.swift* file updated by the tokenator.
+/// `GridRawTokens` are tokens to use to define *grids*  using `GridRawToken` type.
+///
 /// Primitive types such as `Int` 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_.
 public enum GridRawTokens {
 
     // ଘ( ･ω･)_/ﾟ･:*:･｡☆
     // Note: So as to help the Figma-JSON-to-Swift parser the values have been added in the Values folder
+    // This trick helps also to write documentation for these tokens as the tokenator cannot generate documentation
 }

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

@@ -12,11 +12,15 @@
 //
 
 /// Defined as the group of all **raw tokens** related to **opacity**.
+/// Values are defined in *OpacityRawTokens+Values.swift* file and generated by the tokenator.
+/// `OpacityRawTokens` are tokens to use to define *opacity* effects thanks to `OpacityRawToken`.
+///
 /// Primitive types such as `Double` 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_.
 public enum OpacityRawTokens {
 
     // ଘ( ･ω･)_/ﾟ･:*:･｡☆
     // Note: So as to help the Figma-JSON-to-Swift parser the values have been added in the Values folder
+    // This trick helps also to write documentation for these tokens as the tokenator cannot generate documentation
 }

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

@@ -12,11 +12,16 @@
 //
 
 /// Defined as the group of all **raw tokens** related to **typography**.
+/// Values are defined in *TypographyRawTokens+Values.swift* file  generated by the tokenator and in *TypographyRawTokens+Composites.swift* updaed manualy by the develoment team.
+/// `TypographyRawTokens` are tokens to use for *typography* thingss , i.e. kind of values to use to render texts. These tokens define the *font family* to apply (`TypographyFontFamilyRawToken`), the *font weight* (`TypographyFontWeightRawToken`)n the *font size* (`TypographyFontSizeRawToken`) and also the line height (`TypographyFontLineHeightRawToken`) and the *font letter spacing* (`TypographyFontLetterSpacingRawToken`).
+/// Combinations of these raw tokens can be made inside `TypographyCompositeRawToken`, which are composite tokens defining in the end a specific typography to apply.
+///
 /// Primitive types such as `Int` and `String` 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_.
 public enum TypographyRawTokens {
 
     // ଘ( ･ω･)_/ﾟ･:*:･｡☆
     // Note: So as to help the Figma-JSON-to-Swift parser the values have been added in the Values folder
+    // This trick helps also to write documentation for these tokens as the tokenator cannot generate documentation
 }

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

@@ -11,6 +11,9 @@
 // Software description: A SwiftUI components library with code examples for Orange Unified Design System
 //
 
+// ଘ( ･ω･)_/ﾟ･:*:･｡☆
+// [File generated by the tokenator since at least 21/11/2024]
+
 // swiftlint:disable missing_docs
 
 extension BorderRawTokens {

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

@@ -11,6 +11,9 @@
 // Software description: A SwiftUI components library with code examples for Orange Unified Design System
 //
 
+// ଘ( ･ω･)_/ﾟ･:*:･｡☆
+// [File generated by the tokenator since at least 21/11/2024]
+
 // swiftlint:disable missing_docs
 
 extension ColorRawTokens {

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

@@ -11,6 +11,9 @@
 // Software description: A SwiftUI components library with code examples for Orange Unified Design System
 //
 
+// ଘ( ･ω･)_/ﾟ･:*:･｡☆
+// [File generated by the tokenator since at least 21/11/2024]
+
 // swiftlint:disable missing_docs
 
 extension DimensionRawTokens {

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

@@ -11,16 +11,13 @@
 // Software description: A SwiftUI components library with code examples for Orange Unified Design System
 //
 
-// ଘ( ･ω･)_/ﾟ･:*:･｡☆
-// [File to generate with the tokenator with Figma able to output composites and tokenatoer able to manage them]
-// WARNING: Not synchronized anymore with the Figjam / Figma by developers team
+// [File not generated with the tokenator]
+// WARNING: Not synchronized 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
 
-/// Extracted in a separated file because the  *Figma* JSON to Swift, i.e. the *tokenator* parser is not able to process such composite tokens, and the *Figma* tool is not able to.
-///
-/// **Beware, may result in desynchronization between generated raw tokens values and theses composite raw tokens**
+/// Extracted in a separated file because *Figma* is not able to manage *composite tokens*, even if the design team tinkered them in this tool. So *Figma* cannot output such *composite tokens* to its JSON file, and then *tokenator* cannot process things which do not exist.
 extension ElevationRawTokens {
 
     // MARK: Primitive token - Elevation - Box Shadow

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

@@ -11,6 +11,9 @@
 // Software description: A SwiftUI components library with code examples for Orange Unified Design System
 //
 
+// ଘ( ･ω･)_/ﾟ･:*:･｡☆
+// [File generated by the tokenator since at least 21/11/2024]
+
 // swiftlint:disable missing_docs
 
 extension ElevationRawTokens {

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

@@ -13,7 +13,7 @@
 
 // ଘ( ･ω･)_/ﾟ･:*:･｡☆
 // [File to generate with the tokenator]
-// WARNING: Not synchronized anymore with the Figjam / Figma by developers team
+// WARNING: Not synchronized 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/OpacityRawTokens+Values.swift

@@ -11,6 +11,9 @@
 // Software description: A SwiftUI components library with code examples for Orange Unified Design System
 //
 
+// ଘ( ･ω･)_/ﾟ･:*:･｡☆
+// [File generated by the tokenator since at least 21/11/2024]
+
 // swiftlint:disable missing_docs
 
 extension OpacityRawTokens {

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

@@ -11,16 +11,13 @@
 // Software description: A SwiftUI components library with code examples for Orange Unified Design System 
 //
 
-// ଘ( ･ω･)_/ﾟ･:*:･｡☆
-// [File to generate with the tokenator with Figma able to output composites and tokenatoer able to manage them]
-// WARNING: Not synchronized anymore with the Figjam / Figma by developers team
+// [File not generated with the tokenator]
+// WARNING: Not synchronized 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
 
-/// Extracted in a separated file because the  *Figma* JSON to Swift, i.e. the *tokenator* parser is not able to process such composite tokens, and the *Figma* tool is not able to.
-///
-/// **Beware, may result in desynchronization between generated raw tokens values and theses composite raw tokens**
+/// Extracted in a separated file because *Figma* is not able to manage *composite tokens*, even if the design team tinkered them in this tool. So *Figma* cannot output such *composite tokens* to its JSON file, and then *tokenator* cannot process things which do not exist.
 extension TypographyRawTokens {
 
     // MARK: Primitive token - Typography - Composite