Skip to content

Commit 043e586

Browse files
authored
Clarify documentation of SerialDescriptor.serialName (#2581)
1 parent 3efe324 commit 043e586

File tree

1 file changed

+9
-9
lines changed

1 file changed

+9
-9
lines changed

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

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,14 @@ import kotlinx.serialization.encoding.*
1919
* each structure in a distinguishable and format-agnostic manner.
2020
*
2121
* ### Structure
22-
* Serial descriptor is identified by its [name][serialName] and consists of kind, potentially empty set of
22+
* Serial descriptor is identified by its [name][serialName] and consists of a kind, potentially empty set of
2323
* children elements and additional metadata.
2424
*
2525
* * [serialName] uniquely identifies the descriptor (and the corresponding serializer) for non-generic types.
26-
* For generic types, the actual type substitution is omitted from the string representation and the name
27-
* identifies the family of the serializers without type substitutions. However, type substitution is accounted
28-
* in [equals] and [hashCode] operations, meaning that descriptors of generic classes with the same name, but different type
29-
* arguments, are not equal to each other.
26+
* For generic types, the actual type substitution is omitted from the string representation, and the name
27+
* identifies the family of the serializers without type substitutions. However, type substitution is accounted for
28+
* in [equals] and [hashCode] operations, meaning that descriptors of generic classes with the same name but different type
29+
* arguments are not equal to each other.
3030
* [serialName] is typically used to specify the type of the target class during serialization of polymorphic and sealed
3131
* classes, for observability and diagnostics.
3232
* * [Kind][SerialKind] defines what this descriptor represents: primitive, enum, object, collection etc.
@@ -145,12 +145,12 @@ import kotlinx.serialization.encoding.*
145145
*/
146146
public interface SerialDescriptor {
147147
/**
148-
* Serial name of the descriptor that identifies pair of the associated serializer and target class.
148+
* Serial name of the descriptor that identifies a pair of the associated serializer and target class.
149149
*
150-
* For generated serializers, serial name is equal to the corresponding class's fully-qualified name
150+
* For generated and default serializers, the serial name should be equal to the corresponding class's fully-qualified name
151151
* or, if overridden, [SerialName].
152-
* Custom serializers should provide a unique serial name that identify both the serializable class and
153-
* the serializer itself, ignoring type arguments, if they are present.
152+
* Custom serializers should provide a unique serial name that identifies both the serializable class and
153+
* the serializer itself, ignoring type arguments, if they are present, for example: `my.package.LongAsTrimmedString`
154154
*/
155155
@ExperimentalSerializationApi
156156
public val serialName: String

0 commit comments

Comments
 (0)