From bc00439730d72281fed414bf662fe0e2014045c8 Mon Sep 17 00:00:00 2001
From: Rea Rustagi <85902999+rustagir@users.noreply.github.com>
Date: Tue, 23 Jan 2024 09:54:17 -0500
Subject: [PATCH] DOCSP-28748: bson-kotlin dependency (#147)

* fix link

* fix link

* DOCSP-28748: bson-kotlin note

* vale fix

* JS PR fix

(cherry picked from commit a5cbf35f0bd280cd213db4b4d756e90af27bdc1c)
---
 .../data-formats/serialization.txt            | 52 ++++++++++++++-----
 1 file changed, 38 insertions(+), 14 deletions(-)

diff --git a/source/fundamentals/data-formats/serialization.txt b/source/fundamentals/data-formats/serialization.txt
index d28013af..16f40fad 100644
--- a/source/fundamentals/data-formats/serialization.txt
+++ b/source/fundamentals/data-formats/serialization.txt
@@ -4,6 +4,13 @@
 Kotlin Serialization
 ====================
 
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, data model, conversion
+
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -13,23 +20,26 @@ Kotlin Serialization
 Overview
 --------
 
-The Kotlin driver supports the ``kotlinx.serialization`` library for serializing 
-and deserializing Kotlin objects. 
+The Kotlin driver supports the ``kotlinx.serialization`` library for
+serializing and deserializing Kotlin objects. 
 
-The driver provides an efficient ``Bson`` serializer that can can be used with 
+The driver provides an efficient ``Bson`` serializer that you can use with 
 classes marked as ``@Serializable`` to handle the serialization of Kotlin objects 
-to BSON data. 
-The ``bson-kotlinx`` library also supports :ref:`custom codecs <kotlin-custom-codec>`
-with configurations to encode defaults, encode nulls, and define class 
-discriminators.
+to BSON data.
+
+You can also install the ``bson-kotlinx`` library to support
+:ref:`custom codecs <kotlin-custom-codec>` with configurations to encode
+defaults, encode nulls, and define class discriminators.
 
 .. note::
 
-   To use the ``Codec`` interface instead of the Kotlin serialization library 
-   to specify custom encoding and decoding of Kotlin objects to BSON data, 
-   see the :ref:`Codecs <fundamentals-codecs>` documentation. You might choose
-   Kotlin serialization if you are already familiar with the framework or 
-   you prefer to use an idiomatic Kotlin approach.
+   To learn how to use the ``Codec`` interface instead of the
+   Kotlin serialization library to specify custom encoding and decoding
+   of Kotlin objects to BSON data, see the :ref:`Codecs
+   <fundamentals-codecs>` guide.
+   
+   You might choose Kotlin serialization if you are already familiar
+   with the framework or if you prefer to use an idiomatic Kotlin approach.
 
 Although you can use the Kotlin driver with the Kotlin serialization ``Json`` 
 library, the ``Json`` serializer does *not* directly support BSON value types such
@@ -162,8 +172,22 @@ To create a custom codec, install the ``bson-kotlinx`` dependency to your projec
             <version>{+full-version+}</version>
         </dependency>
 
-Then, you can define your codec using the `KotlinSerializerCodec.create() <apidocs/bson-kotlinx/bson-kotlinx/org.bson.codecs.kotlinx/-kotlin-serializer-codec/-companion/create.html>`__ 
-method and add it to the registry. 
+.. note:: bson-kotlin Dependency
+
+   You can also optionally install the ``bson-kotlin`` dependency
+   through the default codec registry. This dependency uses reflection
+   and the codec registry to support Kotlin data classes, but it does
+   not support certain POJO annotations such as ``BsonDiscriminator``,
+   ``BsonExtraElements``, and ``BsonConstructor``. To learn more, see
+   the `bson-kotlin API documentation <{+api+}/apidocs/bson-kotlin/index.html>`__.
+
+   Generally, we recommend that you install and use the faster
+   ``bson-kotlinx`` library for codec configuration.
+
+Then, you can define your codec using the
+`KotlinSerializerCodec.create()
+<{+api+}/apidocs/bson-kotlinx/bson-kotlinx/org.bson.codecs.kotlinx/-kotlin-serializer-codec/-companion/index.html>`__
+method and add it to the registry.
 
 The following example shows how to create a codec using the 
 ``KotlinSerializerCodec.create()`` method and configure it to not encode defaults: