Add subscribe to query with name section

source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst

@@ -0,0 +1,7 @@
+To subscribe to a query with a name, pass the following arguments to ``subscribe()``:
+
+- ``RealmResults query``: Required. A ``RealmResults`` object that you can create using the
+  :ref:`Realm Query Language <rql>`.
+- ``String name``: Optional. Name for the subscription that you can refer to. 
+
+In the following example, we subscribe to two new named queries.

source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-with-name-js-ts-description.rst

@@ -0,0 +1,7 @@
+To subscribe to a query:
+
+#. Query for the objects that you want to read and write.
+#. Call ``subscribe()`` on the query results to create a sync subscription for
+   objects matching the query.
+#. Pass a ``SubscriptionOptions`` object that contains the ``name`` property to
+   ``subscribe()``.

source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst

@@ -0,0 +1 @@
+To add a name to the subscription, pass a string when you call ``.subscribe()``.

source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst

@@ -0,0 +1,4 @@
+To give a query subscription a name, supply a string name argument for the
+``name`` parameter when you call the :swift-sdk:`.subscribe() 
+<Structs/Results.html#/s:10RealmSwift7ResultsV9subscribe4name11waitForSync7timeoutACyxGSSSg_So07RLMWaitgH4ModeVSdSgtYaKF>`
+method.

source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst

@@ -0,0 +1,61 @@
+.. tabs-drivers::
+
+   tabs:
+     - id: cpp
+       content: |
+
+         .. literalinclude:: /examples/MissingPlaceholders/api.cpp
+            :language: cpp
+            :copyable: false
+
+     - id: csharp
+       content: |
+
+         .. literalinclude:: /examples/MissingPlaceholders/api.cs
+            :language: csharp
+            :copyable: false
+
+     - id: dart
+       content: |
+
+         .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.add-subscription-subscribe-api.dart
+            :language: dart 
+
+     - id: java
+       content: |
+
+         .. literalinclude:: /examples/MissingPlaceholders/api.java
+            :language: java
+            :copyable: false
+
+     - id: java-kotlin
+       content: |
+
+         .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt
+            :language: kotlin
+            :copyable: false
+
+     - id: javascript
+       content: |
+
+         .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-name.js
+            :language: javascript
+
+     - id: kotlin
+       content: |
+
+         .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.subscribe-named-query.kt
+            :language: kotlin
+            :emphasize-lines: 3
+
+     - id: swift
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-with-name.swift
+            :language: swift
+
+     - id: typescript
+       content: |
+
+         .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-name.ts
+            :language: typescript

source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst

@@ -18,8 +18,9 @@
      - id: dart
        content: |
 
-         .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.add-subscription-subscribe-api.dart
-            :language: dart 
+         .. literalinclude:: /examples/MissingPlaceholders/example.dart
+            :language: dart
+            :copyable: false
 
      - id: java
        content: |

source/sdk/sync/manage-sync-subscriptions.txt

@@ -34,11 +34,14 @@ You can manually add, update, and remove subscriptions to determine which
 data syncs to the client device. Or you can subscribe to queries instead of
 or in addition to manually managing subscriptions.
 
-Subscriptions
--------------
+What are Subscriptions?
+-----------------------
 
 When you configure Device Sync in Atlas, you specify which fields your 
-client application can query using **subscriptions**. 
+client application can query. The SDK tracks these queries through a
+**subscription**. When you subscribe to a query, the SDK automatically tracks 
+changes to data matching that subscription, and uploads and downloads relevant
+data.
 
 Each subscription corresponds to a query on **queryable fields** for a 
 specific object type. See :ref:`Queryable Fields <queryable-fields>` 
@@ -48,7 +51,12 @@ For each query subscription, the SDK looks for data matching the query.
 Data matching the subscription, where the user has the appropriate 
 permissions, syncs between clients and the backend application.
 
-You can construct queries with RQL, or one of the SDK-idiomatic query engines.
+The SDK tracks these queries through a **subscription set**, which is a
+collection of subscriptions. You can add, remove, and update subscriptions in
+the subscription set.
+
+You can construct subscription queries with RQL, or one of the SDK-idiomatic
+query engines.
 
 - :ref:`realm-query-language`
 - :ref:`java-filter-data`
@@ -111,33 +119,35 @@ You can:
 
 - Add subscriptions with an optional subscription name:
 
-  - You can subscribe to query ``Results``. This 
-    automatically adds the subscription to the subscription set. 
+  - You can subscribe to a database query. This automatically adds the
+    subscription to the subscription set. 
   - Manually add a subscription to the subscription set with the subscribe API.
     Use this API if you need more control over subscriptions for performance
     optimization or business-logic reasons. See :ref:`Performance Considerations
     <sdks-sync-subscription-performance-considerations>` for more information.
 
-- React to subscription state
-- Update subscriptions with new queries
-- Remove individual subscriptions or all subscriptions for an object type
+- React to subscription state changes.
+- Update subscriptions with new queries.
+- Remove individual subscriptions or all subscriptions for an object type.
 
 .. _sdks-sync-results-subscribe-api:
 
 Subscribe to Queries
 --------------------
 
-To simplify subscription management, the SDK offers APIs to subscribe and
-unsubscribe from a query's ``Results`` set. These APIs abstract away the
-details of manually adding and removing subscriptions. This API is not
-available for all languages. If your preferred language does not provide this
-API, refer to :ref:`sdks-manually-manage-subscriptions`.
+To simplify subscription management, the SDK offers APIs to subscribe to and
+unsubscribe from a query directly. These APIs abstract away the details of
+manually adding and removing subscriptions. This API is not available for all
+languages. If your preferred language does not provide this API, refer to
+:ref:`sdks-manually-manage-subscriptions`.
 
 .. important:: The Subscribe to Queries API is in Preview
 
    The APIs described here are currently in Preview. These APIs may be subject
    to change in the future.
 
+.. _sdks-subscribe-to-query:
+
 Subscribe to a Query
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -151,6 +161,13 @@ This creates an unnamed subscription and adds it to the subscription set,
 similar to :ref:`manually creating a subscription
 <sdks-sync-subscriptions-add-subscription>`.
 
+.. tip::
+
+   If your app works with multiple subscriptions, or if you want to update
+   a subscription, you should add a name when you subscribe to a query. For
+   details, refer to the :ref:`sdks-subscribe-to-query-with-name` section on
+   this page.
+
 .. tabs-drivers::
 
    .. tab::
@@ -200,19 +217,68 @@ similar to :ref:`manually creating a subscription
 
 .. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst
 
+.. _sdks-subscribe-to-query-with-name:
+
 Subscribe to a Query with a Subscription Name
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If your app works with multiple subscriptions, or if you want to update
-a subscription, you may want to add a name when you subscribe to a query.
+a subscription, you should add a name when you subscribe to a query.
 
-You can later use this name to :ref:`update a subscription's query 
-<ios-update-subscriptions-with-new-query>`, :ref:`check for a subscription by 
-name <ios-check-existing-subscriptions-before-adding>`, or :ref:`remove the 
-query by name <ios-remove-query-by-name>`.
+You can later use this name to:
 
-.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-with-name.swift
-   :language: swift
+- :ref:`Check for an existing subscription by name <sdks-check-existing-subscriptions-before-adding>`
+- :ref:`Update a subscription's query <sdks-update-subscriptions-with-new-query>`
+- :ref:`Remove the query by name <sdks-remove-query-by-name>`
+
+.. tabs-drivers::
+
+   .. tab::
+      :tabid: cpp-sdk
+
+      .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst
+
+   .. tab::
+      :tabid: csharp
+
+      .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst
+
+   .. tab::
+      :tabid: dart
+
+      .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query--with-name-description.rst
+
+   .. tab::
+      :tabid: java
+
+      .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst
+
+   .. tab::
+      :tabid: java-kotlin
+
+      .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst
+
+   .. tab::
+      :tabid: javascript
+
+      .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-with-name-js-ts-description.rst
+
+   .. tab::
+      :tabid: kotlin
+
+      .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst
+
+   .. tab::
+      :tabid: swift
+
+      .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst
+
+   .. tab::
+      :tabid: typescript
+
+      .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-with-name-js-ts-description.rst
+
+.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst
 
 Wait for a Query Subscription to Sync
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -392,7 +458,7 @@ subscribe to all the ``Team`` objects, you could do this:
 .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-all-objects-of-a-type.swift
    :language: swift
 
-.. _ios-check-existing-subscriptions-before-adding:
+.. _sdks-check-existing-subscriptions-before-adding:
 
 Check for Existing Subscriptions Before Adding a Subscription
 `````````````````````````````````````````````````````````````
@@ -468,7 +534,7 @@ obtain a new instance of the subscription set before you can update it.
 
 .. include:: /includes/note-sync-state-complete.rst
 
-.. _ios-update-subscriptions-with-new-query:
+.. _sdks-update-subscriptions-with-new-query:
 
 Update Subscriptions with a New Query
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -503,7 +569,7 @@ To remove subscriptions, you can:
 When you remove a subscription query, Realm asynchronously removes the
 synced data that matched the query from the client device.
 
-.. _ios-remove-query-by-name:
+.. _sdks-remove-query-by-name:
 
 Remove a Single Subscription
 ````````````````````````````