Move embedded object content to respective CRUD pages

source/sdk/kotlin/realm-database/crud/create.txt

@@ -45,6 +45,21 @@ To persist a new object to a realm:
 .. literalinclude:: /examples/generated/kotlin/CRUDTest.snippet.create-a-new-object.kt
    :language: kotlin
 
+.. tip:: 
+
+   You can also upsert into a realm using specific criteria. See 
+   :ref:`Upsert a Realm Object <kotlin-upsert-an-object>`.
+
+Create an Embedded Object
+-------------------------
+
+To create an embedded object, assign an instance of the 
+`EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__
+to a parent object's property:
+
+.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.create-embedded-object.kt 
+    :language: kotlin
+
 Create an Object with a Dictionary Property
 -------------------------------------------
 
@@ -80,7 +95,7 @@ For more information, see :ref:`Asymmetric Objects <kotlin-asymmetric-objects>`.
 
 You must create an `AsymmetricRealmObject <{+kotlin-sync-prefix+}io.realm.kotlin.types/-asymmetric-realm-object/index.html>`__  
 using the `insert() <{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.ext/insert.html>`__  
-extension method within a write transaction.
+extension method within a write transaction:
 
 .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt
    :language: kotlin

source/sdk/kotlin/realm-database/crud/delete.txt

@@ -17,10 +17,13 @@ Delete Realm Objects - Kotlin SDK
 
 To delete a realm file, refer to :ref:`Delete a Realm <kotlin-delete-a-realm>`.
 
+Delete a Realm Object
+---------------------
+
 .. _kotlin-delete-an-object:
 
-Delete an Object
-----------------
+Delete a Single Object
+~~~~~~~~~~~~~~~~~~~~~~
 
 To delete an object from a realm:
 
@@ -47,7 +50,7 @@ To delete an object from a realm:
 .. _kotlin-delete-multiple-objects:
 
 Delete Multiple Objects
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 To delete multiple objects from a realm at the same time:
 
@@ -73,7 +76,7 @@ To delete multiple objects from a realm at the same time:
 .. _kotlin-delete-all-objects-of-a-type:
 
 Delete All Objects of a Type
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To delete all objects of a type from a realm:
 
@@ -110,3 +113,27 @@ entries in a few ways:
 
 .. literalinclude:: /examples/generated/kotlin/DeleteTest.snippet.delete-realm-dictionary.kt
    :language: kotlin
+
+Delete an Embedded Object
+-------------------------
+
+.. warning:: Realm Uses Cascading Deletes for Embedded Objects
+
+   When you delete a Realm object, Realm automatically deletes any
+   embedded objects referenced by that object. 
+   If you want the referenced objects to persist after the deletion of the 
+   parent object, use a regular Realm object with a :ref:`to-one relationship 
+   <kotlin-to-one-relationship>` instead.
+
+You can delete an 
+`EmbeddedRealmObject.parent() <{+kotlin-local-prefix+}io.realm.kotlin.ext/parent.html>`__  
+directly or through the parent object. 
+
+To delete only an embedded object, you can fetch and delete a specific 
+embedded object or clear the parent's reference to the embedded object, 
+which also deletes the embedded object instance.  
+
+Deleting the parent object automatically deletes all of its embedded objects. 
+
+.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.delete-embedded-object.kt 
+    :language: kotlin

source/sdk/kotlin/realm-database/crud/update.txt

@@ -50,10 +50,56 @@ as you would a Kotlin Map.
 .. literalinclude:: /examples/generated/kotlin/UpdateTest.snippet.update-realm-dictionary.kt
    :language: kotlin
 
+Update an Embedded Object Property
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To update a property in an 
+`EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__, 
+fetch the object and reassign the embedded object properties in a write 
+transaction:
+
+.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.update-embedded-object.kt 
+    :language: kotlin
+
+Update Realm Objects
+--------------------
+
+.. _kotlin-update-collection:
+
+Update a Collection
+~~~~~~~~~~~~~~~~~~~
+
+To update a collection of objects in a realm:
+
+1. Query a realm for a collection of objects
+   with `realm.query()
+   <{+kotlin-local-prefix+}io.realm.kotlin.query/-realm-query/query.html>`__.
+
+#. Open a write transaction with `realm.write()
+   <{+kotlin-local-prefix+}io.realm.kotlin/-realm/write.html>`__ or
+   `realm.writeBlocking()
+   <{+kotlin-local-prefix+}io.realm.kotlin/-realm/write-blocking.html>`__.
+
+#. Update elements of the set of `RealmResults
+   <{+kotlin-local-prefix+}io.realm.kotlin.query/-realm-results/index.html>`__
+   returned by the query.
+
+.. literalinclude:: /examples/generated/kotlin/CRUDTest.snippet.update-a-collection.kt
+   :language: kotlin
+
+Overwrite an Embedded Object
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To overwrite an embedded object, assign a new embedded object instance to the 
+property in a write transaction:
+
+.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.overwrite-embedded-object.kt 
+    :language: kotlin
+
 .. _kotlin-upsert-an-object:
 
-Upsert Objects
---------------
+Upsert a Realm Object
+---------------------
 
 The **upsert** operation either inserts a new instance of an object or
 updates an existing object that meets certain criteria.
@@ -82,27 +128,3 @@ to use when you upsert an object with an existing primary key:
 
 .. literalinclude:: /examples/generated/kotlin/UpdateTest.snippet.upsert-an-object.kt
    :language: kotlin
-
-.. _kotlin-update-collection:
-
-Update a Collection
--------------------
-
-To update a collection of objects in a realm:
-
-1. Query a realm for a collection of objects
-   with `realm.query()
-   <{+kotlin-local-prefix+}io.realm.kotlin.query/-realm-query/query.html>`__.
-
-#. Open a write transaction with `realm.write()
-   <{+kotlin-local-prefix+}io.realm.kotlin/-realm/write.html>`__ or
-   `realm.writeBlocking()
-   <{+kotlin-local-prefix+}io.realm.kotlin/-realm/write-blocking.html>`__.
-
-#. Update elements of the set of `RealmResults
-   <{+kotlin-local-prefix+}io.realm.kotlin.query/-realm-results/index.html>`__
-   returned by the query.
-
-.. literalinclude:: /examples/generated/kotlin/CRUDTest.snippet.update-a-collection.kt
-   :language: kotlin
-

source/sdk/kotlin/realm-database/schemas/define-realm-object-model.txt

@@ -50,6 +50,23 @@ Realm Schema
 
 .. include:: /includes/realm-schema.rst
 
+Property Annotations
+~~~~~~~~~~~~~~~~~~~~
+
+Annotations add functionality to properties in your Realm object models.  
+You can use annotations for things like marking a property as nullable, setting a primary key, ignoring a property, and more. 
+
+To learn more about the available property annotations, refer to :ref:`Property Annotations <kotlin-property-annotations>`.
+
+Relationship Properties
+~~~~~~~~~~~~~~~~~~~~~~~
+
+You can define relationships between Realm objects in your schema. 
+The Realm Kotlin SDK supports to-one relationships, to-many relationships, 
+inverse relationships, and embedding objects within other objects. 
+
+To learn more about how to define relationships in your Realm object schema, refer to :ref:`Relationships <kotlin-relationships>`.
+
 .. _kotlin-define-a-new-object-type:
 
 Define a New Object Type
@@ -59,8 +76,6 @@ To define a Realm object type:
 
 1. Create a uniquely named Kotlin class that implements the 
    `RealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__ 
-   or 
-   `EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__
    interface. 
 
 #. Add fields to your class. You can add any :ref:`supported data types <kotlin-supported-types>` as a field in your class. 
@@ -81,23 +96,26 @@ when you :ref:`open the realm <kotlin-open-a-realm>`.
 .. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.open-with-class.kt
   :language: kotlin
   :emphasize-lines: 2
-
-Add Property Annotations
-~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. _kotlin-define-embedded-object:
 
-Use annotations to add functionality to properties in your Realm object models.  
-You can use annotations for things like marking a property as nullable, setting a primary key, ignoring a property, and more. 
+Define an Embedded Object
+-------------------------
 
-To learn more about the available property annotations, refer to :ref:`Property Annotations <kotlin-property-annotations>`.
+To define an :ref:`embedded object <kotlin-embedded-objects>`, derive a class from 
+`EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__: 
 
-Define Relationship Properties
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.embedded-object-model.kt 
+    :language: kotlin
 
-You can define relationships between Realm objects in your schema. 
-The Realm Kotlin SDK supports to-one relationships, to-many relationships, 
-inverse relationships, and embedding objects within other objects. 
+Once your embedded object class is defined, you must include its schema in the
+realm's 
+`configuration <{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/index.html>`__
+to use it in your realm instance:
 
-To learn more about how to define relationships in your Realm object schema, refer to :ref:`Relationships <kotlin-relationships>`.
+.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.open-realm-embedded-object.kt 
+    :language: kotlin 
+    :emphasize-lines: 3
 
 Define an Asymmetric Object
 ---------------------------

source/sdk/kotlin/realm-database/schemas/relationships.txt

@@ -149,84 +149,4 @@ Because of this, embedded objects have the following constraints:
    recursively reference an embedded object type as an optional property in its
    own definition.
 
-Define an Embedded Object
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To define an embedded object, derive a class from 
-`EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__: 
-
-.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.embedded-object-model.kt 
-    :language: kotlin
-
-Once your embedded object class is defined, you must include its schema in the
-realm's 
-`configuration <{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/index.html>`__
-to use it in your realm instance:
-
-.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.open-realm-embedded-object.kt 
-    :language: kotlin 
-    :emphasize-lines: 3
-
-Create an Embedded Object
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To create an embedded object, assign an instance of the embedded object
-to a parent object's property:
-
-.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.create-embedded-object.kt 
-    :language: kotlin
-
-
-Update Embedded Object Properties
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To update a property in an embedded object, fetch the object and reassign the 
-embedded object properties in a write transaction:
-
-.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.update-embedded-object.kt 
-    :language: kotlin
-
-
-Overwrite an Embedded Object
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To overwrite an embedded object, assign a new embedded object instance to the 
-property in a write transaction:
-
-.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.overwrite-embedded-object.kt 
-    :language: kotlin
-
-
-Query an Embedded Object
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can query the embedded object directly or through the parent object. 
-You can also use the 
-`EmbeddedRealmObject.parent() <{+kotlin-local-prefix+}io.realm.kotlin.ext/parent.html>`__  
-method to access the parent of the embedded object.
-
-.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.query-embedded-objects.kt 
-    :language: kotlin
-
-
-Delete an Embedded Object
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. warning:: Realm Uses Cascading Deletes for Embedded Objects
-
-   When you delete a Realm object, Realm automatically deletes any
-   embedded objects referenced by that object. 
-   If you want the referenced objects to persist after the deletion of the 
-   parent object, use a regular Realm object with a :ref:`to-one relationship 
-   <kotlin-to-one-relationship>` instead.
-
-You can delete an embedded object directly or through the parent object. 
-
-To delete only an embedded object, you can fetch and delete a specific embedded object 
-or clear the parent's reference to the embedded object, which also deletes 
-the embedded object instance.  
-
-Deleting the parent object automatically deletes all of its embedded objects. 
-
-.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.delete-embedded-object.kt 
-    :language: kotlin
+To define an embedded object, refer to :ref:`Define an Embedded Object <kotlin-define-embedded-object>`.