add kdocs for adapters

Author: CJCrafter

src/main/kotlin/com/cjcrafter/openai/gson/ChatChoiceChunkAdapter.kt

@@ -10,26 +10,43 @@ import com.google.gson.stream.JsonReader
 import com.google.gson.stream.JsonToken
 import com.google.gson.stream.JsonWriter
 
+/**
+ * A Gson TypeAdapter for serializing and deserializing the `ChatChoiceChunk`
+ * data class to and from JSON. This adapter handles the `delta` field of the
+ * `ChatChoiceChunk` class, which can be either a string or an object.
+ */
 class ChatChoiceChunkAdapter : TypeAdapter<ChatChoiceChunk?>() {
 
+    /**
+     * Serializes a `ChatChoiceChunk` object to JSON.
+     * If the provided value is null, it is serialized to a JSON null value.
+     *
+     * @param writer The JsonWriter to which the value should be written.
+     * @param value The value to be serialized.
+     */
     override fun write(writer: JsonWriter, value: ChatChoiceChunk?) {
-        if (value == null) {
+        writer.beginObject()
+        writer.name("index").value(value!!.index)
+        writer.name("message").jsonValue(GsonBuilder().create().toJson(value.message))
+        writer.name("delta").value(value.delta)
+        writer.name("finish_reason")
+
+        // in general, it is bad practice to save a message in progress (but yes... you can do it)
+        if (value.finishReason == null) {
             writer.nullValue()
         } else {
-            writer.beginObject()
-            writer.name("index").value(value.index)
-            writer.name("message").jsonValue(GsonBuilder().create().toJson(value.message))
-            writer.name("delta").value(value.delta)
-            writer.name("finish_reason")
-            if (value.finishReason == null) {
-                writer.nullValue()
-            } else {
-                writer.value(value.finishReason!!.name.lowercase())
-            }
-            writer.endObject()
+            writer.value(value.finishReason!!.name.lowercase())
         }
+        writer.endObject()
     }
 
+    /**
+     * Deserializes a JSON string to a `ChatChoiceChunk` object.
+     *
+     * @param reader The JsonReader from which the value should be read.
+     * @return The deserialized `ChatChoiceChunk` object, or null if the JSON value is null.
+     * @throws IllegalArgumentException if the provided string cannot be parsed to a valid `ChatChoiceChunk` object.
+     */
     override fun read(reader: JsonReader): ChatChoiceChunk? {
         var index: Int = -1
         var message: ChatMessage? = null
@@ -47,6 +64,8 @@ class ChatChoiceChunkAdapter : TypeAdapter<ChatChoiceChunk?>() {
                     }
                 }
                 "delta" -> {
+                    // delta -> map when returned from OpenAI (we can ignore it since we use #update(json)).
+                    // delta -> string when we store it as json.
                     when (reader.peek()) {
                         JsonToken.BEGIN_OBJECT -> reader.skipValue()
                         else -> delta = reader.nextString()
@@ -63,6 +82,9 @@ class ChatChoiceChunkAdapter : TypeAdapter<ChatChoiceChunk?>() {
         }
         reader.endObject()
 
+        // when message == null, that means that a message has not been
+        // provided yet. This means it is the first json message from OpenAI.
+        // In this case, ChatUser is always assistant.
         return ChatChoiceChunk(index, message ?: ChatMessage(ChatUser.ASSISTANT, ""), delta ?: "", finishReason)
     }
 }

src/main/kotlin/com/cjcrafter/openai/gson/ChatUserAdapter.kt

@@ -6,8 +6,19 @@ import com.google.gson.stream.JsonReader
 import com.google.gson.stream.JsonToken
 import com.google.gson.stream.JsonWriter
 
+/**
+ * A Gson TypeAdapter for serializing and deserializing the `ChatUser` enum class to and from JSON.
+ */
 class ChatUserAdapter : TypeAdapter<ChatUser?>() {
 
+    /**
+     * Serializes a `ChatUser` enum value to a JSON string.
+     * If the provided value is null, it is serialized to a JSON null value.
+     * Otherwise, it is serialized to a lowercase string representation of its name.
+     *
+     * @param writer The JsonWriter to which the value should be written.
+     * @param value The value to be serialized.
+     */
     override fun write(writer: JsonWriter, value: ChatUser?) {
         if (value == null) {
             writer.nullValue()
@@ -16,6 +27,16 @@ class ChatUserAdapter : TypeAdapter<ChatUser?>() {
         }
     }
 
+    /**
+     * Deserializes a JSON string to a `ChatUser` enum value.
+     * If the provided JSON value is null, this method returns null.
+     * Otherwise, it expects a string representation of a `ChatUser` enum value in uppercase format.
+     * If the provided string cannot be parsed to a valid `ChatUser` enum value, this method throws an exception.
+     *
+     * @param reader The JsonReader from which the value should be read.
+     * @return The deserialized `ChatUser` value, or null if the JSON value is null.
+     * @throws IllegalArgumentException if the provided string cannot be parsed to a valid `ChatUser` enum value.
+     */
     override fun read(reader: JsonReader): ChatUser? {
         return if (reader.peek() == JsonToken.NULL) {
             reader.nextNull()

src/main/kotlin/com/cjcrafter/openai/gson/FinishReasonAdapter.kt

@@ -6,8 +6,20 @@ import com.google.gson.stream.JsonReader
 import com.google.gson.stream.JsonToken
 import com.google.gson.stream.JsonWriter
 
+/**
+ * A Gson TypeAdapter for serializing and deserializing the FinishReason enum
+ * class to and from JSON.
+ */
 class FinishReasonAdapter : TypeAdapter<FinishReason?>() {
 
+    /**
+     * Serializes a FinishReason enum value to a JSON string.
+     * If the provided value is null, it is serialized to a JSON null value.
+     * Otherwise, it is serialized to a lowercase string representation of its name.
+     *
+     * @param writer The JsonWriter to which the value should be written.
+     * @param value The value to be serialized.
+     */
     override fun write(writer: JsonWriter, value: FinishReason?) {
         if (value == null) {
             writer.nullValue()
@@ -16,6 +28,15 @@ class FinishReasonAdapter : TypeAdapter<FinishReason?>() {
         }
     }
 
+    /**
+     * Deserializes a JSON string to a FinishReason enum value.
+     * If the provided JSON value is null, this method returns null.
+     * If the provided string cannot be parsed to a valid FinishReason enum value, this method throws an exception.
+     *
+     * @param reader The JsonReader from which the value should be read.
+     * @return The deserialized FinishReason value, or null if the JSON value is null.
+     * @throws IllegalArgumentException if the provided string cannot be parsed to a valid FinishReason enum value.
+     */
     override fun read(reader: JsonReader): FinishReason? {
         return if (reader.peek() == JsonToken.NULL) {
             reader.nextNull()