Add KDoc for annotated string related classes

Author: florentmaitre

core/src/main/java/com/orange/ouds/core/component/common/text/OudsAnnotatedAlertMessageBulletListLabel.kt

@@ -14,17 +14,63 @@ package com.orange.ouds.core.component.common.text
 
 import androidx.compose.ui.text.AnnotatedString
 
+/**
+ * An annotated string for bullet list items within alert messages.
+ *
+ * This class supports both strong (bold/emphasized) text and clickable links to create
+ * rich, interactive bullet points in alert messages. It is used by [com.orange.ouds.core.component.OudsAlertMessage] component.
+ *
+ * Use [buildOudsAnnotatedAlertMessageBulletListLabel] to create instances:
+ * ```
+ * val bulletList = listOf(
+ *     buildOudsAnnotatedAlertMessageBulletListLabel {
+ *         withStrong { append("Data security:") }
+ *         append(" Your information will be encrypted")
+ *     },
+ *     buildOudsAnnotatedAlertMessageBulletListLabel {
+ *         append("For more information, visit our ")
+ *         withLink(OudsLinkAnnotation.Url("https://help.example.com")) {
+ *             append("help center")
+ *         }
+ *     }
+ * )
+ *
+ * OudsAlertMessage(
+ *     label = "Important information",
+ *     bulletList = bulletList
+ * )
+ * ```
+ */
 class OudsAnnotatedAlertMessageBulletListLabel internal constructor(annotatedString: AnnotatedString) :
     OudsAnnotatedString<OudsAnnotatedAlertMessageBulletListLabel>(annotatedString) {
 
+    /**
+     * Builder for creating [OudsAnnotatedAlertMessageBulletListLabel] with strong text and link formatting.
+     *
+     * Supports both strong text and link annotations through [addStrong], [pushStrong],
+     * [addLink], and [pushLink] methods, or more conveniently through the [withStrong]
+     * and [withLink] DSL helpers.
+     *
+     * @param capacity Initial capacity for the underlying string builder. Defaults to 16.
+     */
     class Builder(capacity: Int = 16) :
         OudsAnnotatedString.Builder<OudsAnnotatedAlertMessageBulletListLabel>(capacity, OudsAnnotatedAlertMessageBulletListLabel::class.java),
         StrongBuilder, LinkBuilder {
 
+        /**
+         * Creates a builder initialized with plain text.
+         *
+         * @param text The initial text content.
+         */
         constructor(text: String) : this() {
             append(text)
         }
 
+        /**
+         * Creates a builder initialized with an existing annotated helper text.
+         *
+         * @param text The initial annotated text to copy.
+         */
         constructor(text: OudsAnnotatedHelperText) : this() {
             append(text)
         }
@@ -41,6 +87,20 @@ class OudsAnnotatedAlertMessageBulletListLabel internal constructor(annotatedStr
     }
 }
 
+/**
+ * Creates an [OudsAnnotatedAlertMessageBulletListLabel] using a builder DSL.
+ *
+ * Example:
+ * ```
+ * val bullet = buildOudsAnnotatedAlertMessageBulletListLabel {
+ *     withStrong { append("Privacy policy:") }
+ *     append(" We respect your privacy and will not share your data")
+ * }
+ * ```
+ *
+ * @param builder Lambda with receiver for building the annotated string.
+ * @return The constructed annotated alert message bullet list label.
+ */
 fun buildOudsAnnotatedAlertMessageBulletListLabel(builder: (OudsAnnotatedAlertMessageBulletListLabel.Builder).() -> Unit): OudsAnnotatedAlertMessageBulletListLabel {
     return buildOudsAnnotatedString<OudsAnnotatedAlertMessageBulletListLabel, OudsAnnotatedAlertMessageBulletListLabel.Builder>(builder)
 }

core/src/main/java/com/orange/ouds/core/component/common/text/OudsAnnotatedAlertMessageDescription.kt

@@ -14,17 +14,60 @@ package com.orange.ouds.core.component.common.text
 
 import androidx.compose.ui.text.AnnotatedString
 
+/**
+ * An annotated string for alert message descriptions.
+ *
+ * This class supports both strong (bold/emphasized) text and clickable links to create
+ * rich, informative alert descriptions. It is used by [com.orange.ouds.core.component.OudsAlertMessage] component.
+ *
+ * Use [buildOudsAnnotatedAlertMessageDescription] to create instances:
+ * ```
+ * val description = buildOudsAnnotatedAlertMessageDescription {
+ *     withStrong { append("Important:") }
+ *     append(" Please read the ")
+ *     withLink(OudsLinkAnnotation.Url("https://example.com/terms")) {
+ *         append("terms and conditions")
+ *     }
+ *     append(" carefully before proceeding")
+ * }
+ *
+ * OudsAlertMessage(
+ *     label = "Before you continue",
+ *     description = description,
+ *     status = OudsAlertMessageStatus.Warning
+ * )
+ * ```
+ */
 class OudsAnnotatedAlertMessageDescription internal constructor(annotatedString: AnnotatedString) :
     OudsAnnotatedString<OudsAnnotatedAlertMessageDescription>(annotatedString) {
 
+    /**
+     * Builder for creating [OudsAnnotatedAlertMessageDescription] with strong text and link formatting.
+     *
+     * Supports both strong text and link annotations through [addStrong], [pushStrong],
+     * [addLink], and [pushLink] methods, or more conveniently through the [withStrong]
+     * and [withLink] DSL helpers.
+     *
+     * @param capacity Initial capacity for the underlying string builder. Defaults to 16.
+     */
     class Builder(capacity: Int = 16) :
         OudsAnnotatedString.Builder<OudsAnnotatedAlertMessageDescription>(capacity, OudsAnnotatedAlertMessageDescription::class.java),
         StrongBuilder, LinkBuilder {
 
+        /**
+         * Creates a builder initialized with plain text.
+         *
+         * @param text The initial text content.
+         */
         constructor(text: String) : this() {
             append(text)
         }
 
+        /**
+         * Creates a builder initialized with an existing annotated helper text.
+         *
+         * @param text The initial annotated text to copy.
+         */
         constructor(text: OudsAnnotatedHelperText) : this() {
             append(text)
         }
@@ -41,6 +84,24 @@ class OudsAnnotatedAlertMessageDescription internal constructor(annotatedString:
     }
 }
 
+/**
+ * Creates an [OudsAnnotatedAlertMessageDescription] using a builder DSL.
+ *
+ * Example:
+ * ```
+ * val description = buildOudsAnnotatedAlertMessageDescription {
+ *     withStrong { append("Note:") }
+ *     append(" Your data will be encrypted and stored securely. ")
+ *     append("For more details, see our ")
+ *     withLink(OudsLinkAnnotation.Url("https://example.com/privacy")) {
+ *         append("privacy policy")
+ *     }
+ * }
+ * ```
+ *
+ * @param builder Lambda with receiver for building the annotated string.
+ * @return The constructed annotated alert message description.
+ */
 fun buildOudsAnnotatedAlertMessageDescription(builder: (OudsAnnotatedAlertMessageDescription.Builder).() -> Unit): OudsAnnotatedAlertMessageDescription {
     return buildOudsAnnotatedString<OudsAnnotatedAlertMessageDescription, OudsAnnotatedAlertMessageDescription.Builder>(builder)
 }

core/src/main/java/com/orange/ouds/core/component/common/text/OudsAnnotatedBulletListLabel.kt

@@ -14,17 +14,58 @@ package com.orange.ouds.core.component.common.text
 
 import androidx.compose.ui.text.AnnotatedString
 
+/**
+ * An annotated string for bullet list item labels.
+ *
+ * This class supports both strong (bold/emphasized) text and clickable links to create
+ * rich, interactive bullet list items. It is used by [com.orange.ouds.core.component.OudsBulletList] component.
+ *
+ * Use [buildOudsAnnotatedBulletListLabel] to create instances:
+ * ```
+ * OudsBulletList {
+ *     item(label = buildOudsAnnotatedBulletListLabel {
+ *         withStrong { append("Important:") }
+ *         append(" Read this carefully")
+ *     })
+ *     item(label = buildOudsAnnotatedBulletListLabel {
+ *         append("For more information, visit our ")
+ *         withLink(OudsLinkAnnotation.Url("https://help.example.com")) {
+ *             append("help center")
+ *         }
+ *     })
+ * }
+ * ```
+ */
 class OudsAnnotatedBulletListLabel internal constructor(annotatedString: AnnotatedString) :
     OudsAnnotatedString<OudsAnnotatedBulletListLabel>(annotatedString) {
 
+    /**
+     * Builder for creating [OudsAnnotatedBulletListLabel] with strong text and link formatting.
+     *
+     * Supports both strong text and link annotations through [addStrong], [pushStrong],
+     * [addLink], and [pushLink] methods, or more conveniently through the [withStrong]
+     * and [withLink] DSL helpers.
+     *
+     * @param capacity Initial capacity for the underlying string builder. Defaults to 16.
+     */
     class Builder(capacity: Int = 16) :
         OudsAnnotatedString.Builder<OudsAnnotatedBulletListLabel>(capacity, OudsAnnotatedBulletListLabel::class.java),
         StrongBuilder, LinkBuilder {
 
+        /**
+         * Creates a builder initialized with plain text.
+         *
+         * @param text The initial text content.
+         */
         constructor(text: String) : this() {
             append(text)
         }
 
+        /**
+         * Creates a builder initialized with an existing annotated helper text.
+         *
+         * @param text The initial annotated text to copy.
+         */
         constructor(text: OudsAnnotatedHelperText) : this() {
             append(text)
         }
@@ -41,6 +82,22 @@ class OudsAnnotatedBulletListLabel internal constructor(annotatedString: Annotat
     }
 }
 
+/**
+ * Creates an [OudsAnnotatedBulletListLabel] using a builder DSL.
+ *
+ * Example:
+ * ```
+ * val label = buildOudsAnnotatedBulletListLabel {
+ *     append("Product details available on our ")
+ *     withLink(OudsLinkAnnotation.Url("https://example.com/products")) {
+ *         append("website")
+ *     }
+ * }
+ * ```
+ *
+ * @param builder Lambda with receiver for building the annotated string.
+ * @return The constructed annotated bullet list label.
+ */
 fun buildOudsAnnotatedBulletListLabel(builder: (OudsAnnotatedBulletListLabel.Builder).() -> Unit): OudsAnnotatedBulletListLabel {
     return buildOudsAnnotatedString<OudsAnnotatedBulletListLabel, OudsAnnotatedBulletListLabel.Builder>(builder)
 }

core/src/main/java/com/orange/ouds/core/component/common/text/OudsAnnotatedErrorMessage.kt

@@ -14,15 +14,56 @@ package com.orange.ouds.core.component.common.text
 
 import androidx.compose.ui.text.AnnotatedString
 
+/**
+ * An annotated string for error messages in OUDS components.
+ *
+ * This class supports strong (bold/emphasized) text formatting to highlight critical
+ * information in error messages. It is used by components like [com.orange.ouds.core.component.OudsTextInput],
+ * [com.orange.ouds.core.component.OudsTextArea], [com.orange.ouds.core.component.OudsPasswordInput], [com.orange.ouds.core.component.OudsPinCodeInput], [com.orange.ouds.core.component.OudsCheckboxItem],
+ * [com.orange.ouds.core.component.OudsRadioButtonItem], and [com.orange.ouds.core.component.OudsSwitchItem] through the [com.orange.ouds.core.component.common.OudsError] class.
+ *
+ * Use [buildOudsAnnotatedErrorMessage] to create instances:
+ * ```
+ * val errorMessage = buildOudsAnnotatedErrorMessage {
+ *     append("This field ")
+ *     withStrong { append("cannot") }
+ *     append(" be empty")
+ * }
+ *
+ * OudsTextInput(
+ *     textFieldState = rememberTextFieldState(),
+ *     label = "Email",
+ *     error = OudsError(annotatedMessage = errorMessage)
+ * )
+ * ```
+ */
 class OudsAnnotatedErrorMessage internal constructor(annotatedString: AnnotatedString) : OudsAnnotatedString<OudsAnnotatedErrorMessage>(annotatedString) {
 
+    /**
+     * Builder for creating [OudsAnnotatedErrorMessage] with strong text formatting.
+     *
+     * Supports strong text annotation through [addStrong] and [pushStrong] methods,
+     * or more conveniently through the [withStrong] DSL helper.
+     *
+     * @param capacity Initial capacity for the underlying string builder. Defaults to 16.
+     */
     class Builder(capacity: Int = 16) : OudsAnnotatedString.Builder<OudsAnnotatedErrorMessage>(capacity, OudsAnnotatedErrorMessage::class.java),
         StrongBuilder {
 
+        /**
+         * Creates a builder initialized with plain text.
+         *
+         * @param text The initial text content.
+         */
         constructor(text: String) : this() {
             append(text)
         }
 
+        /**
+         * Creates a builder initialized with an existing annotated error message.
+         *
+         * @param text The initial annotated text to copy.
+         */
         constructor(text: OudsAnnotatedErrorMessage) : this() {
             append(text)
         }
@@ -33,6 +74,20 @@ class OudsAnnotatedErrorMessage internal constructor(annotatedString: AnnotatedS
     }
 }
 
+/**
+ * Creates an [OudsAnnotatedErrorMessage] using a builder DSL.
+ *
+ * Example:
+ * ```
+ * val errorMessage = buildOudsAnnotatedErrorMessage {
+ *     append("The code you entered is ")
+ *     withStrong { append("incorrect") }
+ * }
+ * ```
+ *
+ * @param builder Lambda with receiver for building the annotated string.
+ * @return The constructed annotated error message.
+ */
 fun buildOudsAnnotatedErrorMessage(builder: (OudsAnnotatedErrorMessage.Builder).() -> Unit): OudsAnnotatedErrorMessage {
     return buildOudsAnnotatedString<OudsAnnotatedErrorMessage, OudsAnnotatedErrorMessage.Builder>(builder)
 }