Clarify that it is preferable to have unique class' serial name (#3098)

Fixes #3003

Author: sandwwraith

core/commonMain/src/kotlinx/serialization/Annotations.kt

@@ -148,7 +148,10 @@ public annotation class Serializer(
  * println(Json.encodeToString(CustomName(42)))
  * ```
  *
- * If a name of class or property is overridden with this annotation, original source code name is not available for the library.
+ * When picking a serial name for a class, avoid assigning the same name to different classes.
+ * Check out Equality rules for [SerialDescriptor] to make sure that class descriptor will stay unique.
+ *
+ * If a name of a class or property is overridden with this annotation, the original source code name is not available for the library.
  * Tools like `JsonNamingStrategy` and `ProtoBufSchemaGenerator` would see and transform [value] from [SerialName] annotation.
  */
 @MustBeDocumented

core/commonMain/src/kotlinx/serialization/descriptors/SerialDescriptors.kt

@@ -93,6 +93,7 @@ public fun PrimitiveSerialDescriptor(serialName: String, kind: PrimitiveKind): S
 /**
  * Factory to create a new descriptor that is identical to [original] except that the name is equal to [serialName].
  * Usually used when you want to serialize a type as another type, delegating implementation of `serialize` and `deserialize`.
+ * Do not use [serialName] that is equal to the name of [original] or other serializable classes.
  *
  * Example:
  * ```

docs/polymorphism.md

@@ -234,6 +234,10 @@ This way we can have a stable _serial name_ that is not affected by the class's
 > In addition to that, JSON can be configured to use a different key name for the class discriminator. 
 > You can find an example in the [Class discriminator for polymorphism](json.md#class-discriminator-for-polymorphism) section.
 
+> [!IMPORTANT]
+> When picking a serial name for a class, avoid assigning the same name to different classes.
+Check out equality rules in documentation for [SerialDescriptor] to make sure that the class descriptor will stay unique.
+
 ### Concrete properties in a base class
 
 A base class in a sealed hierarchy can have properties with backing fields. 
@@ -1017,6 +1021,10 @@ The next chapter covers [JSON features](json.md).
 [DeserializationStrategy]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-deserialization-strategy/index.html
 [SerializationStrategy]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serialization-strategy/index.html
 
+<!--- INDEX kotlinx-serialization-core/kotlinx.serialization.descriptors -->
+
+[SerialDescriptor]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.descriptors/-serial-descriptor/index.html
+
 <!--- INDEX kotlinx-serialization-core/kotlinx.serialization.modules -->
 
 [SerializersModule]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.modules/-serializers-module/index.html
@@ -1037,4 +1045,3 @@ The next chapter covers [JSON features](json.md).
 [Json]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/index.html
 
 <!--- END -->
-