fix(docs): Update KDocs, fix links and cross-references (#476)

- Fix broken links in KDocs and introducing valid references to related
API components.
- Enhanced descriptions
- Also added clarity by linking to specification classes directly for
better usability.

Author: kpavlov

ai-mocks-a2a-models/src/commonMain/kotlin/dev/mokksy/aimocks/a2a/model/AgentSkill.kt

@@ -30,7 +30,7 @@ public data class AgentSkill(
     /**
      * A set of keywords describing the skill's capabilities.
      *
-     * @sample ["cooking", "customer support", "billing"]
+     * Example: `["cooking", "customer support", "billing"]`
      */
     @SerialName("tags")
     val tags: List<String>,
@@ -39,7 +39,7 @@ public data class AgentSkill(
      * Example prompts or scenarios that this skill can handle. Provides a hint to
      * the client on how to use the skill.
      *
-     * @sample ["I need a recipe for bread"]
+     * Example: `["I need a recipe for bread"]`
      */
     @SerialName("examples")
     val examples: List<String>? = null,
@@ -58,12 +58,12 @@ public data class AgentSkill(
 
     /**
      * Security schemes necessary for the agent to leverage this skill.
-     * As in the overall AgentCard.security, this list represents a logical OR of security
+     * As in the overall [AgentCard.security], this list represents a logical OR of security
      * requirement objects. Each object is a set of security schemes that must be used together
      * (a logical AND).
      *
-     * @sample
-     * ```
+     * Example:
+     * ```kotlin
      * [
      *   {
      *     "google": [ "oidc" ]
@@ -76,7 +76,7 @@ public data class AgentSkill(
 ) {
     public companion object {
         /**
-         * Creates a new AgentSkill using the DSL builder.
+         * Creates a new [AgentSkill] using the DSL builder.
          *
          * @param init The lambda to configure the agent skill.
          * @return A new AgentSkill instance.

ai-mocks-a2a-models/src/commonMain/kotlin/dev/mokksy/aimocks/a2a/model/CancelTaskRequestBuilder.kt

@@ -83,7 +83,7 @@ public fun cancelTaskRequest(init: Consumer<CancelTaskRequestBuilder>): CancelTa
 }
 
 /**
- * DSL extension for [CancelTaskRequest.Companion].
+ * DSL extension for [CancelTaskRequest].
  *
  * @param init The lambda to configure the cancel task request.
  * @return A new [CancelTaskRequest] instance.
@@ -93,7 +93,7 @@ public fun CancelTaskRequest.Companion.create(
 ): CancelTaskRequest = CancelTaskRequestBuilder().apply(init).build()
 
 /**
- * Java-friendly DSL extension for [CancelTaskRequest.Companion].
+ * Java-friendly DSL extension for [CancelTaskRequest].
  *
  * @param init The consumer to configure the cancel task request.
  * @return A new [CancelTaskRequest] instance.

ai-mocks-a2a-models/src/commonMain/kotlin/dev/mokksy/aimocks/a2a/model/CancelTaskResponseBuilder.kt

@@ -111,7 +111,7 @@ public fun cancelTaskResponse(init: Consumer<CancelTaskResponseBuilder>): Cancel
 }
 
 /**
- * DSL extension for [CancelTaskResponse.Companion].
+ * DSL extension for [CancelTaskResponse].
  *
  * @param init The lambda to configure the cancel task response.
  * @return A new [CancelTaskResponse] instance.
@@ -121,7 +121,7 @@ public fun CancelTaskResponse.Companion.create(
 ): CancelTaskResponse = CancelTaskResponseBuilder().apply(init).build()
 
 /**
- * Java-friendly DSL extension for [CancelTaskResponse.Companion].
+ * Java-friendly DSL extension for [CancelTaskResponse].
  *
  * @param init The consumer to configure the cancel task response.
  * @return A new [CancelTaskResponse] instance.

ai-mocks-a2a-models/src/commonMain/kotlin/dev/mokksy/aimocks/a2a/model/DeleteTaskPushNotificationConfigRequestBuilder.kt

@@ -96,7 +96,7 @@ public fun deleteTaskPushNotificationConfigRequest(
 }
 
 /**
- * DSL extension for [DeleteTaskPushNotificationConfigRequest.Companion].
+ * DSL extension for [DeleteTaskPushNotificationConfigRequest].
  *
  * @param init The lambda to configure the delete task push notification config request.
  * @return A new [DeleteTaskPushNotificationConfigRequest] instance.
@@ -107,7 +107,7 @@ public fun DeleteTaskPushNotificationConfigRequest.Companion.create(
     DeleteTaskPushNotificationConfigRequestBuilder().apply(init).build()
 
 /**
- * Java-friendly DSL extension for [DeleteTaskPushNotificationConfigRequest.Companion].
+ * Java-friendly DSL extension for [DeleteTaskPushNotificationConfigRequest].
  *
  * @param init The consumer to configure the delete task push notification config request.
  * @return A new [DeleteTaskPushNotificationConfigRequest] instance.

ai-mocks-a2a-models/src/commonMain/kotlin/dev/mokksy/aimocks/a2a/model/FileContent.kt

@@ -8,10 +8,10 @@ import kotlinx.serialization.Serializable
  * Represents the content of a file, either as base64 encoded bytes or a URI.
  *
  * This is a union type that can represent either:
- * - [FileWithBytes]: File content provided directly as base64-encoded bytes
- * - [FileWithUri]: File content located at a specific URI
+ * - File content provided directly as base64-encoded bytes (via [bytes] property)
+ * - File content located at a specific URI (via [uri] property)
  *
- * Either 'bytes' or 'uri' should be provided, but not both.
+ * Either [bytes] or [uri] should be provided, but not both.
  */
 @Serializable
 public data class FileContent(
@@ -29,15 +29,15 @@ public data class FileContent(
 
     /**
      * The base64-encoded content of the file.
-     * Present when representing a [FileWithBytes].
+     * Present when representing file content directly.
      */
     @Serializable(with = ByteArrayAsBase64Serializer::class)
     @SerialName("bytes")
     val bytes: ByteArray? = null,
 
     /**
      * A URL pointing to the file's content.
-     * Present when representing a [FileWithUri].
+     * Present when representing file content via URI.
      */
     @SerialName("uri")
     val uri: String? = null,

ai-mocks-a2a-models/src/commonMain/kotlin/dev/mokksy/aimocks/a2a/model/GetAuthenticatedExtendedCardRequestBuilder.kt

@@ -63,7 +63,7 @@ public fun getAuthenticatedExtendedCardRequest(
 }
 
 /**
- * DSL extension for [GetAuthenticatedExtendedCardRequest.Companion].
+ * DSL extension for [GetAuthenticatedExtendedCardRequest].
  *
  * @param init The lambda to configure the get authenticated extended card request.
  * @return A new [GetAuthenticatedExtendedCardRequest] instance.
@@ -74,7 +74,7 @@ public fun GetAuthenticatedExtendedCardRequest.Companion.create(
     GetAuthenticatedExtendedCardRequestBuilder().apply(init).build()
 
 /**
- * Java-friendly DSL extension for [GetAuthenticatedExtendedCardRequest.Companion].
+ * Java-friendly DSL extension for [GetAuthenticatedExtendedCardRequest].
  *
  * @param init The consumer to configure the get authenticated extended card request.
  * @return A new [GetAuthenticatedExtendedCardRequest] instance.

ai-mocks-a2a-models/src/commonMain/kotlin/dev/mokksy/aimocks/a2a/model/GetTaskPushNotificationRequestBuilder.kt

@@ -95,7 +95,7 @@ public fun getTaskPushNotificationRequest(
 }
 
 /**
- * DSL extension for [GetTaskPushNotificationRequest.Companion].
+ * DSL extension for [GetTaskPushNotificationRequest].
  *
  * @param init The lambda to configure the get task push notification request.
  * @return A new [GetTaskPushNotificationRequest] instance.
@@ -105,7 +105,7 @@ public fun GetTaskPushNotificationRequest.Companion.create(
 ): GetTaskPushNotificationRequest = GetTaskPushNotificationRequestBuilder().apply(init).build()
 
 /**
- * Java-friendly DSL extension for [GetTaskPushNotificationRequest.Companion].
+ * Java-friendly DSL extension for [GetTaskPushNotificationRequest].
  *
  * @param init The consumer to configure the get task push notification request.
  * @return A new [GetTaskPushNotificationRequest] instance.

ai-mocks-a2a-models/src/commonMain/kotlin/dev/mokksy/aimocks/a2a/model/GetTaskPushNotificationResponseBuilder.kt

@@ -117,7 +117,7 @@ public fun getTaskPushNotificationResponse(
 }
 
 /**
- * DSL extension for [GetTaskPushNotificationResponse.Companion].
+ * DSL extension for [GetTaskPushNotificationResponse].
  *
  * @param init The lambda to configure the get task push notification response.
  * @return A new [GetTaskPushNotificationResponse] instance.
@@ -127,7 +127,7 @@ public fun GetTaskPushNotificationResponse.Companion.create(
 ): GetTaskPushNotificationResponse = GetTaskPushNotificationResponseBuilder().apply(init).build()
 
 /**
- * Java-friendly DSL extension for [GetTaskPushNotificationResponse.Companion].
+ * Java-friendly DSL extension for [GetTaskPushNotificationResponse].
  *
  * @param init The consumer to configure the get task push notification response.
  * @return A new [GetTaskPushNotificationResponse] instance.

ai-mocks-a2a-models/src/commonMain/kotlin/dev/mokksy/aimocks/a2a/model/GetTaskRequestBuilder.kt

@@ -90,7 +90,7 @@ public fun getTaskRequest(init: Consumer<GetTaskRequestBuilder>): GetTaskRequest
 }
 
 /**
- * DSL extension for [GetTaskRequest.Companion].
+ * DSL extension for [GetTaskRequest].
  *
  * @param init The lambda to configure the get task request.
  * @return A new [GetTaskRequest] instance.
@@ -99,7 +99,7 @@ public fun GetTaskRequest.Companion.create(init: GetTaskRequestBuilder.() -> Uni
     GetTaskRequestBuilder().apply(init).build()
 
 /**
- * Java-friendly DSL extension for [GetTaskRequest.Companion].
+ * Java-friendly DSL extension for [GetTaskRequest].
  *
  * @param init The consumer to configure the get task request.
  * @return A new [GetTaskRequest] instance.

ai-mocks-a2a-models/src/commonMain/kotlin/dev/mokksy/aimocks/a2a/model/GetTaskResponseBuilder.kt

@@ -110,7 +110,7 @@ public fun getTaskResponse(init: Consumer<GetTaskResponseBuilder>): GetTaskRespo
 }
 
 /**
- * DSL extension for [GetTaskResponse.Companion].
+ * DSL extension for [GetTaskResponse].
  *
  * @param init The lambda to configure the get task response.
  * @return A new [GetTaskResponse] instance.
@@ -120,7 +120,7 @@ public fun GetTaskResponse.Companion.create(
 ): GetTaskResponse = GetTaskResponseBuilder().apply(init).build()
 
 /**
- * Java-friendly DSL extension for [GetTaskResponse.Companion].
+ * Java-friendly DSL extension for [GetTaskResponse].
  *
  * @param init The consumer to configure the get task response.
  * @return A new [GetTaskResponse] instance.