Merge pull request #287 from slava110/comments

Added experimental comment support on serialization

src/commonMain/kotlin/com/charleskorn/kaml/YamlComment.kt

@@ -0,0 +1,34 @@
+/*
+
+   Copyright 2018-2021 Charles Korn.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+*/
+
+package com.charleskorn.kaml
+
+import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.SerialInfo
+
+/**
+ * Adds a comment block before property on serialization
+ * @property lines comment lines to add
+ */
+@OptIn(ExperimentalSerializationApi::class)
+@Target(AnnotationTarget.PROPERTY)
+@Retention(AnnotationRetention.BINARY)
+@SerialInfo
+public annotation class YamlComment(
+    vararg val lines: String
+)

src/commonTest/kotlin/com/charleskorn/kaml/YamlWritingTest.kt

@@ -885,6 +885,23 @@ class YamlWritingTest : DescribeSpec({
                 }
             }
         }
+
+        describe("handling comments") {
+            context("comments in kotlin object") {
+                val input = SimpleStructureWithComments("objName", 73, "justTest")
+
+                it("is written") {
+                    Yaml.default.encodeToString(SimpleStructureWithComments.serializer(), input) shouldBe """
+                        name: "objName"
+                        # Cool int
+                        myInt: 73
+                        # Testing
+                        # multiline
+                        test: "justTest"
+                    """.trimIndent()
+                }
+            }
+        }
     }
 })
 
@@ -898,5 +915,17 @@ private data class SimpleStructureWithDefault(
     val name: String = "default"
 )
 
+@Serializable
+private data class SimpleStructureWithComments(
+    val name: String,
+    @YamlComment("Cool int")
+    val myInt: Int,
+    @YamlComment(
+        "Testing",
+        "multiline"
+    )
+    val test: String
+)
+
 @Serializable
 private data class ThingWithMap(val variables: Map<String, String>)

src/jvmMain/kotlin/com/charleskorn/kaml/YamlOutput.kt

@@ -27,9 +27,11 @@ import kotlinx.serialization.encoding.CompositeEncoder
 import kotlinx.serialization.modules.SerializersModule
 import org.snakeyaml.engine.v2.api.DumpSettings
 import org.snakeyaml.engine.v2.api.StreamDataWriter
+import org.snakeyaml.engine.v2.comments.CommentType
 import org.snakeyaml.engine.v2.common.FlowStyle
 import org.snakeyaml.engine.v2.common.ScalarStyle
 import org.snakeyaml.engine.v2.emitter.Emitter
+import org.snakeyaml.engine.v2.events.CommentEvent
 import org.snakeyaml.engine.v2.events.DocumentEndEvent
 import org.snakeyaml.engine.v2.events.DocumentStartEvent
 import org.snakeyaml.engine.v2.events.ImplicitTuple
@@ -90,6 +92,8 @@ internal class YamlOutput(
     private fun emitQuotedScalar(value: String, scalarStyle: ScalarStyle) = emitScalar(value, scalarStyle)
 
     override fun encodeElement(descriptor: SerialDescriptor, index: Int): Boolean {
+        encodeComment(descriptor, index)
+
         if (descriptor.kind is StructureKind.CLASS) {
             emitPlainScalar(descriptor.getElementName(index))
         }
@@ -142,6 +146,20 @@ internal class YamlOutput(
         emitter.emit(StreamEndEvent())
     }
 
+    private fun encodeComment(descriptor: SerialDescriptor, index: Int) {
+        val commentAnno = descriptor.getElementAnnotations(index)
+            .filterIsInstance<YamlComment>()
+            .firstOrNull()
+
+        if (commentAnno == null) {
+            return
+        }
+
+        for (line in commentAnno.lines) {
+            emitter.emit(CommentEvent(CommentType.BLOCK, " $line", Optional.empty(), Optional.empty()))
+        }
+    }
+
     private fun emitScalar(value: String, style: ScalarStyle) {
         val tag = getAndClearTypeName()