style: improve DocC comments (#279)

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

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

@@ -19,10 +19,10 @@ import OUDSTokensSemantic
 // 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`.
-/// These values can be overriden inside `OUDSTheme` subclasses (in extensions or not, in the same module or not) thanks to the `@objc open` combination.
+/// Defines basic values common to all themes for ``ElevationCompositeSemanticTokens``.
+/// These values can be overriden inside ``OUDSTheme`` subclasses (in extensions or not, in the same module or not) thanks to the `@objc open` combination.
 /// The aim of this extensions is to make relationships between all semantic tokens for elevations and associated raw tokens.
-/// `OUDSTheme` can be seen as a kind of "abstract class" in _object oriented paradigm_.
+/// `OUDSTheme`` can be seen as a kind of "abstract class" in _object oriented paradigm_.
 /// The *tokenator* is not able to provide code for such "composite" objects because the *Figma* tool itself cannot manage that and does not output anything in its JSON to process/
 /// It defines in fact box shadows effects.
 extension OUDSTheme: ElevationCompositeSemanticTokens {

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

@@ -20,7 +20,7 @@ import OUDSTokensSemantic
 // Create an issue for update https://github.com/Orange-OpenSource/ouds-ios/issues/new?template=token_update.yml
 
 /// Defines wrapper objects for eelvation color semantic  tokens.
-/// These values can be overriden inside `OUDSTheme` subclasses (in extensions or not, in the same module or not) thanks to the `@objc open` combination.
+/// These values can be overriden inside ``OUDSTheme`` subclasses (in extensions or not, in the same module or not) thanks to the `@objc open` combination.
 extension OUDSTheme: ElevationMultipleSemanticTokens {
 
     @objc open var elevationColorDrag: MultipleColorTokens { MultipleColorTokens(ColorRawTokens.colorTransparentBlack500) }

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

@@ -21,8 +21,8 @@ import OUDSTokensSemantic
 // 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`).
-/// These values can be overriden inside `OUDSTheme` subclasses (in extensions or not, in the same module or not) thanks to the `@objc open` combination.
+/// Defines wrapper objects for size semantic tokens (i.e. in the end ``DimensionRawToken``).
+/// These values can be overriden inside ``OUDSTheme`` subclasses (in extensions or not, in the same module or not) thanks to the `@objc open` combination.
 extension OUDSTheme: SizeMultipleSemanticTokens {
 
     // MARK: - Semantic token - Sizing - Icon with typography

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

@@ -19,8 +19,8 @@ import OUDSTokensSemantic
 // 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`).
-/// These values can be overriden inside `OUDSTheme` subclasses (in extensions or not, in the same module or not) thanks to the `@objc open` combination.
+/// Defines wrapper objects for space semantic tokens (i.e. in the end ``DimensionRawToken`).
+/// These values can be overriden inside ``OUDSTheme`` subclasses (in extensions or not, in the same module or not) thanks to the `@objc open` combination.
 extension OUDSTheme: SpaceMultipleSemanticTokens {
 
     // MARK: Semantic token - Spacing - Layout fluid

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

@@ -21,8 +21,8 @@ import OUDSTokensSemantic
 
 // swiftlint:disable line_length
 
-/// Defines basic values common to all themes for `TypographyCompositeSemanticTokens`.
-/// These values can be overriden inside `OUDSTheme` subclasses (in extensions or not, in the same module or not) thanks to the `@objc open` combination.
+/// Defines basic values common to all themes for ``TypographyCompositeSemanticTokens``.
+/// These values can be overriden inside ``OUDSTheme`` subclasses (in extensions or not, in the same module or not) thanks to the `@objc open` combination.
 /// The aim of this extensions is to make relationships between all composite semantic tokens for typography and associated composite raw tokens.
 /// `OUDSTheme` can be seen as a kind of "abstract class" in _object oriented paradigm_.
 extension OUDSTheme: TypographyCompositeSemanticTokens {

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

@@ -22,7 +22,7 @@ import OUDSTokensSemantic
 // swiftlint:disable line_length
 
 /// Defines wrapper objects for typography semantic tokens but "multiple", i.e. tokens with values depending to size classes or color schemes.
-/// These values can be overriden inside `OUDSTheme` subclasses (in extensions or not, in the same module or not) thanks to the `@objc open` combination.
+/// These values can be overriden inside ``OUDSTheme` subclasses (in extensions or not, in the same module or not) thanks to the `@objc open` combination.
 extension OUDSTheme: TypographyMultipleSemanticTokens {
 
     // MARK: - Semantic token - Typography - Font - Size

OUDS/Core/Themes/Inverse/Sources/InverseTheme+ColorSemanticTokens.swift

@@ -24,7 +24,7 @@ import OUDSTokensSemantic
 // swiftlint:disable line_length
 // swiftlint:disable file_length
 
-/// Overrides some colors using values defined in extension of `ColorRawTokens` in this current module.
+/// Overrides some colors using values defined in extension of ``ColorRawTokens`` in this current module.
 /// Some tokens do not have values assigned in the design system, and must be overriden.
 extension InverseTheme {
 

OUDS/Core/Themes/Inverse/Sources/InverseTheme.swift

@@ -13,7 +13,7 @@
 
 import OUDSThemesOrange
 
-/// This is an override of the default basic `OrangeTheme` with some inverted colors.
+/// This is an override of the default basic ``OrangeTheme`` with some inverted colors.
 /// It can overrides any properties from its superclass, and can be derived too.
 open class InverseTheme: OrangeTheme, @unchecked Sendable {
 

OUDS/Core/Themes/Orange/Sources/OrangeTheme+SemanticColorTokens.swift

@@ -21,7 +21,7 @@ import OUDSTokensSemantic
 
 // swiftlint:disable line_length
 
-/// Overrides some color tokens using values available in `OrangeBrandColorRawTokens`
+/// Overrides some color tokens using values available in ``OrangeBrandColorRawTokens``
 extension OrangeTheme {
 
     // MARK: Semantic token - Colors - Background

OUDS/Core/Themes/Orange/Sources/OrangeTheme.swift

@@ -13,7 +13,7 @@
 
 import OUDS
 
-/// This is an override of the default basic `OUDSTheme` and should be seen as the default theme for the OUDS library.
+/// This is an override of the default basic ``OUDSTheme` and should be seen as the default theme for the OUDS library.
 /// It can overrides any properties from its superclass, and can be derived too.
 open class OrangeTheme: OUDSTheme, @unchecked Sendable {
 

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

@@ -15,7 +15,7 @@ import Foundation
 
 /// 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.
+/// 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

@@ -13,7 +13,7 @@
 
 import OUDSFoundations
 
-/// An operator to make for example comparisons between `TypographyCompositeRawToken`
+/// An operator to make for example comparisons between ``TypographyCompositeRawToken``
 infix operator <|
 
 /// In the *Figma* global design system, composite tokens are defined for typography-related things.

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

@@ -13,8 +13,8 @@
 
 /// 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`).
+/// ``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

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

@@ -13,10 +13,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`.
+/// ``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.
+/// 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 {

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

@@ -13,9 +13,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.
+/// ``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 {

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

@@ -13,11 +13,11 @@
 
 /// 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.
+/// ``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.
+/// 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 {

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

@@ -13,9 +13,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.
+/// ``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.
+/// 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 {

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

@@ -13,9 +13,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`.
+/// ``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.
+/// 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 {

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

@@ -13,16 +13,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* updated manualy by the develoment team.
-/// `TypographyRawTokens` are tokens to use for *typography* thingss , i.e. kind of values to use to render texts.
+/// ``TypographyRawTokens`` are tokens to use for *typography* thinss , i.e. kind of values to use to render texts.
 /// These tokens define:
-///     - the *font family* to apply (`TypographyFontFamilyRawToken`)
-///     - the *font weight* (`TypographyFontWeightRawToken`),
-///     - the *font size* (`TypographyFontSizeRawToken`)
-///     - 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.
+///     - the *font family* to apply (``TypographyFontFamilyRawToken``)
+///     - the *font weight* (``TypographyFontWeightRawToken``),
+///     - the *font size* (``TypographyFontSizeRawToken``)
+///     - 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.
+/// 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 {

OUDS/Core/Tokens/RawTokens/Sources/TypeAliases/BorderRawTokens+Aliases.swift

@@ -11,16 +11,16 @@
 // Software description: A SwiftUI components library with code examples for Orange Unified Design System
 //
 
-/// Type alias precising `Double` value are used (because of multiplier factors) for a **border width raw token**, to keep grammar clean and clear with design system grammar.
+/// Type alias precising ``Double`` value are used (because of multiplier factors) for a **border width raw token**, to keep grammar clean and clear with design system grammar.
 public typealias BorderWidthRawToken = Double
 
-/// Type alias precising `Double` value are used (because of multiplier factors) for a **border radius raw token**, to keep grammar clean and clear with design system grammar.
+/// Type alias precising ``Double`` value are used (because of multiplier factors) for a **border radius raw token**, to keep grammar clean and clear with design system grammar.
 public typealias BorderRadiusRawToken = Double
 
-/// Type alias for `String` so as to help users (developers) to see that raw tokens are needed and linked to `String` for **border style raw token**.
-/// `String` are used here to prevent to rely on _SwiftUI_ types which are not compatible with `@objc` and are heavier than primitive types.
+/// Type alias for ``String`` so as to help users (developers) to see that raw tokens are needed and linked to ``String` for **border style raw token**.
+/// ``String`` are used here to prevent to rely on _SwiftUI_ types which are not compatible with `@objc` and are heavier than primitive types.
 /// In addition, if new styles are defined in design team side (such as kind of composite styles) and need to be processed differently
 /// (because not available with _SwiftUI_ because are composed of several styles),
-/// such  `String` values could be processed later without any API breaks.
+/// such  ``String`` values could be processed later without any API breaks.
 /// Keeps grammar clean and clear with design system grammar.
 public typealias BorderStyleRawToken = String

OUDS/Core/Tokens/RawTokens/Sources/TypeAliases/ColorRawTokens+Aliases.swift

@@ -11,5 +11,5 @@
 // Software description: A SwiftUI components library with code examples for Orange Unified Design System
 //
 
-/// A color raw token is finaly a `String` containing the hexadecimal code of the color, to keep grammar clean and clear with design system grammar.
+/// A color raw token is finaly a ``String` containing the hexadecimal code of the color, to keep grammar clean and clear with design system grammar.
 public typealias ColorRawToken = String

OUDS/Core/Tokens/RawTokens/Sources/TypeAliases/ElevationRawTokens+Aliases.swift

@@ -13,5 +13,5 @@
 
 import Foundation
 
-/// Type aliases precising `CGFloat` values are used (because used in _SwiftUI_ API) for each **elevation raw token**, to keep grammar clean and clear with design system grammar.
+/// Type aliases precising ``CGFloat` values are used (because used in _SwiftUI_ API) for each **elevation raw token**, to keep grammar clean and clear with design system grammar.
 public typealias ElevationRawToken = CGFloat