Updated builtin-classes.md to mention Duration

Resolves #1986

5 files changed, 47 insertions, 2 deletions

diff --git a/core/commonMain/src/kotlinx/serialization/builtins/BuiltinSerializers.kt b/core/commonMain/src/kotlinx/serialization/builtins/BuiltinSerializers.kt
index 10f3f86c..22fecf15 100644
--- a/core/commonMain/src/kotlinx/serialization/builtins/BuiltinSerializers.kt
+++ b/core/commonMain/src/kotlinx/serialization/builtins/BuiltinSerializers.kt
@@ -245,7 +245,7 @@ public fun UShort.Companion.serializer(): KSerializer<UShort> = UShortSerializer
 
 /**
  * Returns serializer for [Duration].
- * It is serialized as a string that represents a duration in the ISO-8601 format.
+ * It is serialized as a string that represents a duration in the ISO-8601-2 format.
  *
  * The result of serialization is similar to calling [Duration.toIsoString], for deserialization is [Duration.parseIsoString].
  */
diff --git a/docs/builtin-classes.md b/docs/builtin-classes.md
index e1c6690a..f8bcedc4 100644
--- a/docs/builtin-classes.md
+++ b/docs/builtin-classes.md
@@ -23,6 +23,7 @@ including the standard collections, is built into Kotlin Serialization. This cha
   * [Deserializing collections](#deserializing-collections)
   * [Maps](#maps)
   * [Unit and singleton objects](#unit-and-singleton-objects)
+  * [Duration](#duration)
 
 <!--- END -->
 
@@ -380,6 +381,30 @@ which is explained in the [Polymorphism. Objects](polymorphism.md#objects) secti
 
 > Serialization of objects is format specific. Other formats may represent objects differently, 
 > e.g. using their fully-qualified names.
+
+### Duration
+
+Since Kotlin `1.7.20` the [Duration] class has become serializable.
+
+<!--- INCLUDE 
+import kotlin.time.*
+-->
+
+```kotlin
+fun main() {
+    val duration = 1000.toDuration(DurationUnit.SECONDS)
+    println(Json.encodeToString(duration))
+}
+```
+> You can get the full code [here](../guide/example/example-builtin-12.kt).
+
+Duration is serialized as a string in the ISO-8601-2 format.
+```text
+"PT16M40S"
+```
+
+<!--- TEST -->
+
 ---
 
 The next chapter covers [Serializers](serializers.md).
@@ -392,6 +417,7 @@ The next chapter covers [Serializers](serializers.md).
 [List]: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/ 
 [Set]: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-set/ 
 [Map]: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/ 
+[Duration]: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.time/-duration/
 
 <!--- MODULE /kotlinx-serialization-core -->
 <!--- INDEX kotlinx-serialization-core/kotlinx.serialization -->
@@ -405,4 +431,3 @@ The next chapter covers [Serializers](serializers.md).
 [LongAsStringSerializer]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.builtins/-long-as-string-serializer/
 
 <!--- END -->
- 
diff --git a/docs/serialization-guide.md b/docs/serialization-guide.md
index e82e4dcc..a1f5f078 100644
--- a/docs/serialization-guide.md
+++ b/docs/serialization-guide.md
@@ -49,6 +49,7 @@ Once the project is set up, we can start serializing some classes.
   * <a name='deserializing-collections'></a>[Deserializing collections](builtin-classes.md#deserializing-collections)
   * <a name='maps'></a>[Maps](builtin-classes.md#maps)
   * <a name='unit-and-singleton-objects'></a>[Unit and singleton objects](builtin-classes.md#unit-and-singleton-objects)
+  * <a name='duration'></a>[Duration](builtin-classes.md#duration)
 <!--- END -->
 
 **Chapter 3.** [Serializers](serializers.md)
diff --git a/guide/example/example-builtin-12.kt b/guide/example/example-builtin-12.kt
new file mode 100644
index 00000000..4bd1da05
--- /dev/null
+++ b/guide/example/example-builtin-12.kt
@@ -0,0 +1,12 @@
+// This file was automatically generated from builtin-classes.md by Knit tool. Do not edit.
+package example.exampleBuiltin12
+
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+
+import kotlin.time.*
+
+fun main() {
+    val duration = 1000.toDuration(DurationUnit.SECONDS)
+    println(Json.encodeToString(duration))
+}
diff --git a/guide/test/BuiltinClassesTest.kt b/guide/test/BuiltinClassesTest.kt
index 28273328..5c964ace 100644
--- a/guide/test/BuiltinClassesTest.kt
+++ b/guide/test/BuiltinClassesTest.kt
@@ -82,4 +82,11 @@ class BuiltinClassesTest {
             "{}"
         )
     }
+
+    @Test
+    fun testExampleBuiltin12() {
+        captureOutput("ExampleBuiltin12") { example.exampleBuiltin12.main() }.verifyOutputLines(
+            "\"PT16M40S\""
+        )
+    }
 }