Actualize Protobuf documentation (#2355)

Fixes #2352

2 files changed, 28 insertions, 22 deletions

diff --git a/formats/protobuf/commonMain/src/kotlinx/serialization/protobuf/ProtoBuf.kt b/formats/protobuf/commonMain/src/kotlinx/serialization/protobuf/ProtoBuf.kt
index 6ca6a3ce..92bb2f5e 100644
--- a/formats/protobuf/commonMain/src/kotlinx/serialization/protobuf/ProtoBuf.kt
+++ b/formats/protobuf/commonMain/src/kotlinx/serialization/protobuf/ProtoBuf.kt
@@ -11,12 +11,14 @@ import kotlin.js.*
 
 /**
  * Implements [encoding][encodeToByteArray] and [decoding][decodeFromByteArray] classes to/from bytes
- * using [Proto2][https://developers.google.com/protocol-buffers/docs/proto] specification.
- * It is typically used by constructing an application-specific instance, with configured specific behaviour
+ * using [Protocol buffers](https://protobuf.dev/) specification.
+ * It is typically used by constructing an application-specific instance, with configured specific behavior
  * and, if necessary, registered custom serializers (in [SerializersModule] provided by [serializersModule] constructor parameter).
+ * Default encoding is proto2, although proto3 can be used with a number of tweaks (see the section below for details).
+ *
  *
  * ### Correspondence between Protobuf message definitions and Kotlin classes
- * Given a ProtoBuf definition with one required field, one optional field and one optional field with a custom default
+ * Given a ProtoBuf definition with one required field, one optional field, and one optional field with a custom default
  * value:
  * ```
  * message MyMessage {
@@ -32,27 +34,29 @@ import kotlin.js.*
  * data class MyMessage(val first: Int, val second: Int = 0, val third: Int = 42)
  * ```
  *
- * By default, protobuf fields ids are being assigned to Kotlin properties in incremental order, i.e.
- * the first property in the class has id 1, the second has id 2, and so forth.
- * If you need a more stable order (e.g. to avoid breaking changes when reordering properties),
- * provide custom ids using [ProtoNumber] annotation.
+ * By default, protobuf fields numbers are being assigned to Kotlin properties in incremental order, i.e.,
+ * the first property in the class has number 1, the second has number 2, and so forth.
+ * If you need a more stable order (e.g., to avoid breaking changes when reordering properties),
+ * provide custom numbers using [ProtoNumber] annotation.
  *
- * By default, all integer numbers are encoded using [varint][https://developers.google.com/protocol-buffers/docs/encoding#varints]
- * encoding. This behaviour can be changed via [ProtoType] annotation.
+ * By default, all integer values are encoded using [varint](https://protobuf.dev/programming-guides/encoding/#varints)
+ * encoding. This behavior can be changed via [ProtoType] annotation.
  *
  * ### Known caveats and limitations
  * Lists are represented as repeated fields. Because format spec says that if the list is empty,
- * there are no elements in the stream with such tag, you must explicitly mark any
- * field of list type with default = emptyList(). Same for maps.
- * There's no special support for `oneof` protobuf fields. However, this implementation
+ * there are no elements in the stream with such tag, you have to explicitly add to any
+ * property of `List` type a default value equals to `emptyList()`. Same for maps.
+ * There is no special support for `oneof` protobuf fields. However, this implementation
  * supports standard kotlinx.serialization's polymorphic and sealed serializers,
- * using their default form (message of serialName: string and other embedded message with actual content).
+ * using their default form (message consisting of `serialName: string` and other embedded message with actual content).
  *
  * ### Proto3 support
- * This implementation does not support repeated packed fields, so you won't be able to deserialize
- * Proto3 lists. However, other messages could be decoded. You have to remember that since fields in Proto3
- * messages by default are implicitly optional,
- * corresponding Kotlin properties have to be nullable with default value `null`.
+ *
+ * proto2 and proto3 specifications use the same encoding, so you can use this class to decode Proto3 messages.
+ * However, the message structure is slightly different, so you should remember the following:
+ *
+ * - In proto3, fields by default are implicitly optional, so corresponding Kotlin properties have to be nullable and have a default value `null`.
+ * - In proto3, all lists use packed encoding by default. To be able to decode them, annotation [ProtoPacked] should be used on all properties with type `List`.
  *
  * ### Usage example
  * ```
@@ -112,6 +116,9 @@ import kotlin.js.*
  * @param encodeDefaults specifies whether default values are encoded.
  *                       False by default; meaning that properties with values equal to defaults will be elided.
  * @param serializersModule application-specific [SerializersModule] to provide custom serializers.
+ * @see ProtoNumber
+ * @see ProtoType
+ * @see ProtoPacked
  */
 @ExperimentalSerializationApi
 public sealed class ProtoBuf(
diff --git a/formats/protobuf/commonMain/src/kotlinx/serialization/protobuf/ProtoTypes.kt b/formats/protobuf/commonMain/src/kotlinx/serialization/protobuf/ProtoTypes.kt
index 3b62d4dc..109ffb83 100644
--- a/formats/protobuf/commonMain/src/kotlinx/serialization/protobuf/ProtoTypes.kt
+++ b/formats/protobuf/commonMain/src/kotlinx/serialization/protobuf/ProtoTypes.kt
@@ -11,7 +11,7 @@ import kotlinx.serialization.descriptors.*
  * Specifies protobuf field number (a unique number for a field in the protobuf message)
  * assigned to a Kotlin property.
  *
- * See [https://developers.google.com/protocol-buffers/docs/proto#assigning-field-numbers]
+ * See [Assigning field numbers](https://protobuf.dev/programming-guides/proto2/#assigning) for details.
  */
 @SerialInfo
 @Target(AnnotationTarget.PROPERTY)
@@ -19,15 +19,14 @@ import kotlinx.serialization.descriptors.*
 public annotation class ProtoNumber(public val number: Int)
 
 /**
- * Represents a number format in protobuf encoding.
+ * Represents a number format in protobuf encoding set by [ProtoType] annotation.
  *
  * [DEFAULT] is default varint encoding (intXX),
  * [SIGNED] is signed ZigZag representation (sintXX), and
  * [FIXED] is fixedXX type.
  * uintXX and sfixedXX are not supported yet.
  *
- * See [https://developers.google.com/protocol-buffers/docs/proto#scalar]
- * @see ProtoType
+ * See [Scalar value types](https://protobuf.dev/programming-guides/proto2/#scalar) for details.
  */
 @Suppress("NO_EXPLICIT_VISIBILITY_IN_API_MODE_WARNING")
 @ExperimentalSerializationApi
@@ -48,7 +47,7 @@ public annotation class ProtoType(public val type: ProtoIntegerType)
 
 
 /**
- * Instructs that a particular collection should be written as [packed array](https://developers.google.com/protocol-buffers/docs/encoding#packed)
+ * Instructs that a particular collection should be written as a [packed array](https://protobuf.dev/programming-guides/encoding/#packed).
  */
 @SerialInfo
 @Target(AnnotationTarget.PROPERTY)