Merge remote-tracking branch 'origin/master' into dev

Author: sandwwraith

README.md

@@ -175,12 +175,62 @@ dependencies {
 
 ### Android
 
-Library should work on Android "as is". If you're using proguard, you need
-to add this to your `proguard-rules.pro`:
+The library works on Android, but, if you're using ProGuard,
+you need to add rules to your `proguard-rules.pro` configuration to cover all classes that are serialized at runtime.
 
+The following configuration keeps serializers for _all_ serializable classes that are retained after shrinking.
+Uncomment and modify the last section in case you're serializing classes with named companion objects.
+
+```proguard
+# Keep `Companion` object fields of serializable classes.
+# This avoids serializer lookup through `getDeclaredClasses` as done for named companion objects.
+-if @kotlinx.serialization.Serializable class **
+-keepclassmembers class <1> {
+    static <1>$Companion Companion;
+}
+
+# Keep `serializer()` on companion objects (both default and named) of serializable classes.
+-if @kotlinx.serialization.Serializable class ** {
+    static **$* *;
+}
+-keepclassmembers class <1>$<3> {
+    kotlinx.serialization.KSerializer serializer(...);
+}
+
+# Keep `INSTANCE.serializer()` of serializable objects.
+-if @kotlinx.serialization.Serializable class ** {
+    public static ** INSTANCE;
+}
+-keepclassmembers class <1> {
+    public static <1> INSTANCE;
+    kotlinx.serialization.KSerializer serializer(...);
+}
+
+# @Serializable and @Polymorphic are used at runtime for polymorphic serialization.
+-keepattributes RuntimeVisibleAnnotations,AnnotationDefault
+
+# Serializer for classes with named companion objects are retrieved using `getDeclaredClasses`.
+# If you have any, uncomment and replace classes with those containing named companion objects.
+#-keepattributes InnerClasses # Needed for `getDeclaredClasses`.
+#-if @kotlinx.serialization.Serializable class
+#com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions.
+#com.example.myapplication.HasNamedCompanion2
+#{
+#    static **$* *;
+#}
+#-keepnames class <1>$$serializer { # -keepnames suffices; class is kept when serializer() is kept.
+#    static <1>$$serializer INSTANCE;
+#}
+```
+
+In case you want to exclude serializable classes that are used, but never serialized at runtime,
+you will need to write custom rules with narrower [class specifications](https://www.guardsquare.com/manual/configuration/usage).
+
+<details>
+<summary>Example of custom rules</summary>
+ 
 ```proguard
--keepattributes *Annotation*, InnerClasses
--dontnote kotlinx.serialization.AnnotationsKt # core serialization annotations
+-keepattributes RuntimeVisibleAnnotations,AnnotationDefault
 
 # kotlinx-serialization-json specific. Add this if you have java.lang.NoClassDefFoundError kotlinx.serialization.json.JsonObjectSerializer
 -keepclassmembers class kotlinx.serialization.json.** {
@@ -190,17 +240,30 @@ to add this to your `proguard-rules.pro`:
     kotlinx.serialization.KSerializer serializer(...);
 }
 
+# Application rules
+
 # Change here com.yourcompany.yourpackage
--keep,includedescriptorclasses class com.yourcompany.yourpackage.**$$serializer { *; } # <-- change package name to your app's
--keepclassmembers class com.yourcompany.yourpackage.** { # <-- change package name to your app's
+-keepclassmembers @kotlinx.serialization.Serializable class com.yourcompany.yourpackage.** {
+    # lookup for plugin generated serializable classes
     *** Companion;
+    # lookup for serializable objects
+    *** INSTANCE;
+    kotlinx.serialization.KSerializer serializer(...);
 }
--keepclasseswithmembers class com.yourcompany.yourpackage.** { # <-- change package name to your app's
+# lookup for plugin generated serializable classes
+-if @kotlinx.serialization.Serializable class com.yourcompany.yourpackage.**
+-keepclassmembers class com.yourcompany.yourpackage.<1>$Companion {
     kotlinx.serialization.KSerializer serializer(...);
 }
-```
 
-You may also want to keep all custom serializers you've defined.
+# Serialization supports named companions but for such classes it is necessary to add an additional rule.
+# This rule keeps serializer and serializable class from obfuscation. Therefore, it is recommended not to use wildcards in it, but to write rules for each such class.
+-keepattributes InnerClasses # Needed for `getDeclaredClasses`.
+-keep class com.yourcompany.yourpackage.SerializableClassWithNamedCompanion$$serializer {
+    *** INSTANCE;
+}
+```
+</details>
 
 ### Multiplatform (Common, JS, Native)
 

docs/polymorphism.md

@@ -367,7 +367,7 @@ We can update the previous example and turn `Project` superclass into an interfa
 mark an interface itself as `@Serializable`. No problem. Interfaces cannot have instances by themselves.
 Interfaces can only be represented by instances of their derived classes. Interfaces are used in the Kotlin language to enable polymorphism, 
 so all interfaces are considered to be implicitly serializable with the [PolymorphicSerializer]
-strategy. We just need to mark thier implementing classes as `@Serializable` and register them. 
+strategy. We just need to mark their implementing classes as `@Serializable` and register them. 
 
 <!--- INCLUDE 
 import kotlinx.serialization.modules.*

formats/README.md

@@ -95,13 +95,13 @@ This library allows serialization and deserialization of objects into and from A
 
 ### XML
 * GitHub repo: [pdvrieze/xmlutil](https://github.com/pdvrieze/xmlutil)
-* Artifact ID: `net.devrieze:xmlutil-serialization`
+* Artifact ID: `io.github.pdvrieze.xmlutil:serialization`
 * Platform: JVM, Android, JavaScript
 
 This library allows for reading and writing of XML documents with the serialization library.
 It is multiplatform, but as the xmlutil library (which handles the multiplatform xml bit) 
 delegates to platform specific parsers each platform needs to  be implemented for each platform 
-specifically. The library is designed to handle existing formats that use features that would 
+specifically. The library is designed to handle existing xml formats that use features that would 
 not be available in other formats such as JSON.
 
 ### YAML
@@ -135,4 +135,12 @@ Allow serialization and deserialization of objects to and from [CBOR](https://cb
 * Artifact ID: `com.github.dimitark:kotlinx-serialization-ion`
 * Platform: JVM
 
-Allow serialization and deserialization of objects to and from [Amazon Ion](https://amzn.github.io/ion-docs/). It stores the data in a flat binary format. Upon destialization, it retains the references between the objects. 
+Allow serialization and deserialization of objects to and from [Amazon Ion](https://amzn.github.io/ion-docs/). It stores the data in a flat binary format. Upon destialization, it retains the references between the objects.
+
+### android.os.Bundle
+
+* GitHub repo: [AhmedMourad0/bundlizer](https://github.com/AhmedMourad0/bundlizer)
+* Artifact ID: `dev.ahmedmourad.bundlizer:bundlizer-core`
+* Platform: Android
+
+Allow serialization and deserialization of objects to and from [android.os.Bundle](https://developer.android.com/reference/android/os/Bundle).