Update docs

Author: xiaozhikang0916

docs/formats.md

@@ -19,6 +19,8 @@ stable, these are currently experimental features of Kotlin Serialization.
   * [Lists as repeated fields](#lists-as-repeated-fields)
   * [Packed fields](#packed-fields)
   * [Oneof field (experimental)](#oneof-field-experimental)
+    * [Usage](#usage)
+    * [Alternative](#alternative)
   * [ProtoBuf schema generator (experimental)](#protobuf-schema-generator-experimental)
 * [Properties (experimental)](#properties-experimental)
 * [Custom formats (experimental)](#custom-formats-experimental)

docs/serialization-guide.md

@@ -152,6 +152,8 @@ Once the project is set up, we can start serializing some classes.
   * <a name='lists-as-repeated-fields'></a>[Lists as repeated fields](formats.md#lists-as-repeated-fields)
   * <a name='packed-fields'></a>[Packed fields](formats.md#packed-fields)
   * <a name='oneof-field-experimental'></a>[Oneof field (experimental)](formats.md#oneof-field-experimental)
+    * <a name='usage'></a>[Usage](formats.md#usage)
+    * <a name='alternative'></a>[Alternative](formats.md#alternative)
   * <a name='protobuf-schema-generator-experimental'></a>[ProtoBuf schema generator (experimental)](formats.md#protobuf-schema-generator-experimental)
 * <a name='properties-experimental'></a>[Properties (experimental)](formats.md#properties-experimental)
 * <a name='custom-formats-experimental'></a>[Custom formats (experimental)](formats.md#custom-formats-experimental)

guide/example/example-formats-08.kt

@@ -4,14 +4,21 @@ package example.exampleFormats08
 import kotlinx.serialization.*
 import kotlinx.serialization.protobuf.*
 
+// The outer class
 @Serializable
 data class Data(
     @ProtoNumber(1) val name: String,
     @ProtoOneOf val phone: IPhoneType,
 )
+
+// The oneof interface
 @Serializable sealed interface IPhoneType
-@Serializable @ProtoNumber(2) @JvmInline value class HomePhone(val number: String): IPhoneType
-@Serializable @ProtoNumber(3) data class WorkPhone(val number: String): IPhoneType
+
+// Message holder for home_phone
+@Serializable @JvmInline value class HomePhone(@ProtoNumber(2) val number: String): IPhoneType
+
+// Message holder for work_phone
+@Serializable data class WorkPhone(@ProtoNumber(3) val number: String): IPhoneType
 
 fun main() {
   val dataTom = Data("Tom", HomePhone("123"))

guide/example/example-formats-09.kt

@@ -1,6 +1,12 @@
 // This file was automatically generated from formats.md by Knit tool. Do not edit.
 package example.exampleFormats09
 
+@Serializable  
+data class Data2(  
+    @ProtoNumber(1) val name: String,  
+    @ProtoNumber(2) val homeNumber: String? = null,  
+    @ProtoNumber(3) val workNumber: String? = null,  
+)  
 import kotlinx.serialization.*
 import kotlinx.serialization.protobuf.*
 import kotlinx.serialization.protobuf.schema.ProtoBufSchemaGenerator