From f8cc5e2bbfab1764ce58ed53017938bdf347ee30 Mon Sep 17 00:00:00 2001
From: Pierre-Yves Lapersonne <pierreyves.lapersonne@orange.com>
Date: Thu, 21 Nov 2024 11:57:17 +0100
Subject: [PATCH] docs: update DocC comments and catalog for raw tokens (#279)

Signed-off-by: Pierre-Yves Lapersonne <pierreyves.lapersonne@orange.com>
---
 .../ElevationCompositeRawToken.swift           |  5 ++++-
 .../TypographyCompositeRawToken.swift          |  6 ++++--
 .../Sources/Declarations/BorderRawTokens.swift |  5 ++++-
 .../Sources/Declarations/ColorRawTokens.swift  |  5 +++++
 .../Declarations/DimensionRawTokens.swift      |  4 ++++
 .../Declarations/ElevationRawTokens.swift      |  5 +++++
 .../Sources/Declarations/GridRawTokens.swift   |  4 ++++
 .../Declarations/OpacityRawTokens.swift        |  4 ++++
 .../Declarations/TypographyRawTokens.swift     |  5 +++++
 .../Values/BorderRawTokens+Values.swift        |  3 +++
 .../Sources/Values/ColorRawTokens+Values.swift |  3 +++
 .../Values/DimensionRawTokens+Values.swift     |  3 +++
 .../Values/ElevationRawTokens+Composites.swift |  9 +++------
 .../Values/ElevationRawTokens+Values.swift     |  3 +++
 .../Sources/Values/GridRawTokens+Values.swift  |  2 +-
 .../Values/OpacityRawTokens+Values.swift       |  3 +++
 .../TypographyRawTokens+Composites.swift       |  9 +++------
 .../_OUDSTokensRaw.docc/OUDSTokensRaw.md       | 18 ++++++++++--------
 18 files changed, 71 insertions(+), 25 deletions(-)

diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Composites/ElevationCompositeRawToken.swift b/OUDS/Core/Tokens/RawTokens/Sources/Composites/ElevationCompositeRawToken.swift
index bf2ec32c1..ca0c004be 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Composites/ElevationCompositeRawToken.swift
+++ b/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
 
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Composites/TypographyCompositeRawToken.swift b/OUDS/Core/Tokens/RawTokens/Sources/Composites/TypographyCompositeRawToken.swift
index 228db285a..cddf5ef91 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Composites/TypographyCompositeRawToken.swift
+++ b/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
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Declarations/BorderRawTokens.swift b/OUDS/Core/Tokens/RawTokens/Sources/Declarations/BorderRawTokens.swift
index 63cb3e617..c8a01e971 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Declarations/BorderRawTokens.swift
+++ b/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
 }
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Declarations/ColorRawTokens.swift b/OUDS/Core/Tokens/RawTokens/Sources/Declarations/ColorRawTokens.swift
index f83ad3b18..8f1afc4a0 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Declarations/ColorRawTokens.swift
+++ b/OUDS/Core/Tokens/RawTokens/Sources/Declarations/ColorRawTokens.swift
@@ -12,6 +12,10 @@
 //
 
 /// 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_.
@@ -19,6 +23,7 @@ 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:
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Declarations/DimensionRawTokens.swift b/OUDS/Core/Tokens/RawTokens/Sources/Declarations/DimensionRawTokens.swift
index 4c45081e7..eac314a2a 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Declarations/DimensionRawTokens.swift
+++ b/OUDS/Core/Tokens/RawTokens/Sources/Declarations/DimensionRawTokens.swift
@@ -12,6 +12,9 @@
 //
 
 /// 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_.
@@ -19,4 +22,5 @@ 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
 }
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Declarations/ElevationRawTokens.swift b/OUDS/Core/Tokens/RawTokens/Sources/Declarations/ElevationRawTokens.swift
index dd0b1856b..d25280d8a 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Declarations/ElevationRawTokens.swift
+++ b/OUDS/Core/Tokens/RawTokens/Sources/Declarations/ElevationRawTokens.swift
@@ -12,6 +12,10 @@
 //
 
 /// 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_.
@@ -19,4 +23,5 @@ 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
 }
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Declarations/GridRawTokens.swift b/OUDS/Core/Tokens/RawTokens/Sources/Declarations/GridRawTokens.swift
index 97fe45feb..5663383a0 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Declarations/GridRawTokens.swift
+++ b/OUDS/Core/Tokens/RawTokens/Sources/Declarations/GridRawTokens.swift
@@ -12,6 +12,9 @@
 //
 
 /// 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_.
@@ -19,4 +22,5 @@ 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
 }
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Declarations/OpacityRawTokens.swift b/OUDS/Core/Tokens/RawTokens/Sources/Declarations/OpacityRawTokens.swift
index dd65c69b0..7e879a75d 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Declarations/OpacityRawTokens.swift
+++ b/OUDS/Core/Tokens/RawTokens/Sources/Declarations/OpacityRawTokens.swift
@@ -12,6 +12,9 @@
 //
 
 /// 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_.
@@ -19,4 +22,5 @@ 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
 }
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Declarations/TypographyRawTokens.swift b/OUDS/Core/Tokens/RawTokens/Sources/Declarations/TypographyRawTokens.swift
index dfac38b26..edf8f87c1 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Declarations/TypographyRawTokens.swift
+++ b/OUDS/Core/Tokens/RawTokens/Sources/Declarations/TypographyRawTokens.swift
@@ -12,6 +12,10 @@
 //
 
 /// 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_.
@@ -19,4 +23,5 @@ 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
 }
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Values/BorderRawTokens+Values.swift b/OUDS/Core/Tokens/RawTokens/Sources/Values/BorderRawTokens+Values.swift
index 976a05194..e950db0a5 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Values/BorderRawTokens+Values.swift
+++ b/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 {
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Values/ColorRawTokens+Values.swift b/OUDS/Core/Tokens/RawTokens/Sources/Values/ColorRawTokens+Values.swift
index 7d966debb..df45303b0 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Values/ColorRawTokens+Values.swift
+++ b/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 {
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Values/DimensionRawTokens+Values.swift b/OUDS/Core/Tokens/RawTokens/Sources/Values/DimensionRawTokens+Values.swift
index 0b006a238..8c6ef51dd 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Values/DimensionRawTokens+Values.swift
+++ b/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 {
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Values/ElevationRawTokens+Composites.swift b/OUDS/Core/Tokens/RawTokens/Sources/Values/ElevationRawTokens+Composites.swift
index 63db830b0..8b79fd24f 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Values/ElevationRawTokens+Composites.swift
+++ b/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
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Values/ElevationRawTokens+Values.swift b/OUDS/Core/Tokens/RawTokens/Sources/Values/ElevationRawTokens+Values.swift
index 73b8acf65..4303c2d10 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Values/ElevationRawTokens+Values.swift
+++ b/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 {
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Values/GridRawTokens+Values.swift b/OUDS/Core/Tokens/RawTokens/Sources/Values/GridRawTokens+Values.swift
index 874f3aa4e..e900335a0 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Values/GridRawTokens+Values.swift
+++ b/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
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Values/OpacityRawTokens+Values.swift b/OUDS/Core/Tokens/RawTokens/Sources/Values/OpacityRawTokens+Values.swift
index 20ddb1d34..22170f4db 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Values/OpacityRawTokens+Values.swift
+++ b/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 {
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/Values/TypographyRawTokens+Composites.swift b/OUDS/Core/Tokens/RawTokens/Sources/Values/TypographyRawTokens+Composites.swift
index 734a9e74b..5fc2729e6 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/Values/TypographyRawTokens+Composites.swift
+++ b/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
diff --git a/OUDS/Core/Tokens/RawTokens/Sources/_OUDSTokensRaw.docc/OUDSTokensRaw.md b/OUDS/Core/Tokens/RawTokens/Sources/_OUDSTokensRaw.docc/OUDSTokensRaw.md
index 60c1b3f22..9d196c2d2 100644
--- a/OUDS/Core/Tokens/RawTokens/Sources/_OUDSTokensRaw.docc/OUDSTokensRaw.md
+++ b/OUDS/Core/Tokens/RawTokens/Sources/_OUDSTokensRaw.docc/OUDSTokensRaw.md
@@ -4,15 +4,15 @@ _Raw tokens_ are smallest _tokens_ possible. They are associated to raw values a
 
 ## Overview
 
-In fact, we choose to use as most as possible primitive types for raw values, like `Int`, `Double`, `CGFloat` or `String` so as to handle the smallest types with few impacts on the memory for ecodesign principles. Indeed with hundreds of raw tokens, it will be more efficient to store primitive small types than Swift `struct` or `class` objects.
+In fact, we choose to use as most as possible primitive types for raw values, like `Int`, `Double`, `CGFloat` or `String` so as to handle the smallest types with few impacts on the memory for ecodesign principles. Indeed with hundreds of raw tokens, it will be more efficient to store primitive small types than Swift `struct` or `class` objects. Keeping primitive types helps today to expose objects using Objective-C runtime.
 
 So we expose also in higher level some properties so as to convert when needed some of these types to `SwiftUI` types (like `Font.Weight` and `Color`).
 
-To keep the same semantics as the ones used in our specifications, _typealias_ are used to as to make the links to _primitive types_ and our logic of _tokens_. These type aliases are available for those who want to make their own theme.
+To keep the same semantics as the ones used in our specifications, _typealias_ are used to as to make the links to _primitive types_ and our logic of _tokens_. These type aliases are available for those who want to make their own theme. The idea is to use the same words and grammar as the one used in the *Figma* kit and generaly in the global design system. Then users won't feel lost and will be able to see the same notions the design team handle.
 
 Using more simple and primitive types will help also to test the library. With also type aliases we force users to use our types and not higher level types like _SwiftUI_ types.
 
-We also choose to add in _extension_ all the tokens values in a separated file so as to help the *Figma*-JSON-to-Swift parser to build files to copy and paste easily in the project and keeping all the other objects.
+We also choose to add in _extension_ all the tokens values in a separated file so as to help the *tokenator* to build files to copy and paste easily in the project and keeping all the other objects. In fact, declaring the tokens *enums* in seperated file helps us to document the associated tokens. The tokens are defined in an extension inside dedicated file which can be overriden anytime ; the result is trasnparent for the users.
 
 Example for ``ColorRawTokens``:
 
@@ -20,8 +20,10 @@ Example for ``ColorRawTokens``:
 // Define types for color raw tokens
 public typealias ColorRawToken = String
 
+/// Possible to write documentation in a seperated file
 public enum ColorRawTokens { } // Gathers all color raw tokens
 
+/// Place in another file which can be updated anytime
 extension ColorRawTokens { // In a separated file
 
     public static let colorFunctionalWhite: ColorRawToken = "#FFFFFF"
@@ -40,8 +42,8 @@ extension String {
 ## Architecture
 
 The *Composites* folder contains some _composite class_ defined to match the objects available in *Figma*.
-In fact the design system implementations should expose pack of values so as to gather several tokens in one object. For exemple `ElevationCompositeRawToken` can be used for predefined elevations effects, and `TypographyCompositeRawToken` can be used for predefined typography.
-All such *composites* are defined here.
+In fact the design system implementations should expose pack of values so as to gather several tokens in one object. For exemple `ElevationCompositeRawToken` can be used for predefined elevations / box shadows effects, and `TypographyCompositeRawToken` can be used for predefined typography.
+All such *composites* instances are defined in seperated files. In fact *tokenator* cannot generate such tokens as they are not defined in its JSON file to process because *Figma* is not able to manage *composite tokens*, even if tinkered by the design team. These tokens are updated manualy by the development team.
 
 The *Declarations* folder contains all the Swift `enum` objects which will gather the raw tokens.
 In fact, raw tokens are defined as `static let` _stored properties_, an adding them in an `enum` is more optimized for namespaces reasons. Thus all `public enum` gathering raw tokens are defined there.
@@ -50,7 +52,7 @@ The *TypeAliases* folder contains all the *typealias* values used for the raw to
 Indeed these aliases are here to bring clarity and meanings in the library, and also to help users (i.e. developers) to know what kind of objects they handle with the same vocabulary as the one used in *Figma*, and in general, in the whole design system. They can be seen as a ligh level of abstraction with meanings, without having to define real types with `struct` or `class`.
 
 The *Values* folder is maybe the hotter one.
-In fact all the raw tokens values are defined there, and if a JSON to Swift parser generate files, these files must be stored there. It contains only pure raw tokens Swift values, without any type aliases definitions or objects declarations. Generated values are place din _+Values_ files, and composite raw tokens are in _+Composites_.
+In fact all the raw tokens values are defined there, and if the tokenator generates files, these files must be stored there. It contains only pure raw tokens Swift values, without any type aliases definitions or objects declarations. Generated values are place din _+Values_ files, and composite raw tokens are in _+Composites_. Only composites are updated manualy by the development team.
 
 In a nutshell, place the generated values somewhere, and the types and objects elsewhere.
 
@@ -58,7 +60,7 @@ In a nutshell, place the generated values somewhere, and the types and objects e
 
 ### How to add raw tokens
 
-First, you need to define which from family this semantic comes. We have today up to 7 families: *border*, *color*, *dimension*, *elevation*, *grid*, *opacity* and *typography*.
+First, you need to define from which family this semantic comes. We have today up to 7 families: *border*, *color*, *dimension*, *elevation*, *grid*, *opacity* and *typography*.
 If your token is not from one of these groups, maybe you should redesign your token or create a new family. To do that, you will have to create a dedicated Swift `enum`, with a useful name, and declare as a `static let` the raw tokens in an `extension`. If you already know the family, just update the matching files.
 
 If you need to define Swift `typealias`, update the suitable file in the *TypeAliases* folder.
@@ -68,7 +70,7 @@ Please, respect the nomenclature of the files, e.g. for a new family "Awesome ra
 - generated values must be in `AwesomeRawTokens+Values.swift`
 - composite tokens must be in `AwesomeRawTokens+Composites.swift`
 - type aliases must be in `AwesomeRawTokens+Aliases.swift`
-- composites objects must be in `AwesomeCompositeRawTokens.swift`
+- composites objects types must be defined in `AwesomeCompositeRawTokens.swift`
 
 *Composites* here are notions from the *Figjam*, a bit, but *Figma* is not able to manage such gorup of raw tokens. This it cannot output composite raw tokens in the JSON for the parser. 
 As a consequence the composites are defined in a folder, and their values in the *Values* folder in dedicated files.