Apply Lindsey feedback

examples/dart/test/data_types_test.dart

@@ -225,7 +225,9 @@ main() {
       final data = realm.all<RealmValueExample>();
       for (var obj in data) {
         final anyValue = obj.singleAnyValue;
+        // Access the RealmValue.type property 
         switch (anyValue.type) {
+          // Work with the returned RealmValueType enums
           case RealmValueType.int:
             approximateAge = DateTime.now().year - anyValue.as<int>();
             break;

examples/dart/test/read_write_data_test.dart

@@ -205,28 +205,24 @@ void main() {
         ]);
 
         final teams = realm.all<Team>();
-        // Use [bracket notation] to query values at the specified path
+        // Use bracket notation to query values at the specified path
         final teamsWithHighPriorityEvents =
+            // Check any element at that path with [*]
             teams.query("eventLog[*].priority == 'high'");
         print(teamsWithHighPriorityEvents.length); // prints `2`
 
         final teamsWithMaintenanceEvents =
+            // Check for the first element at that path with [FIRST]
             teams.query("eventLog[*].type[FIRST] == 'maintenance'");
         print(teamsWithMaintenanceEvents.length); // prints `1`
 
-        // Use @keys to query map keys
-        final eventsWithComments =
-            teams.query("eventLog[*].@keys == 'comment'");
-        print(eventsWithComments.length); // prints `1`
-
-        // Use @type to query the collection type
         final teamsWithEventsAsLists =
+            // Check the collection type with @type 
             teams.query("eventLog[*].type.@type == 'list'");
         print(teamsWithEventsAsLists.length); // prints `2`
         // :remove-start:
         expect(teamsWithHighPriorityEvents.length, 2);
         expect(teamsWithMaintenanceEvents.length, 1);
-        expect(eventsWithComments.length, 1);
         expect(teamsWithEventsAsLists.length, 2);
         // :remove-end:
       });

source/examples/generated/flutter/data_types_test.snippet.realm-value-type.dart

@@ -1,7 +1,9 @@
 final data = realm.all<RealmValueExample>();
 for (var obj in data) {
   final anyValue = obj.singleAnyValue;
+  // Access the RealmValue.type property 
   switch (anyValue.type) {
+    // Work with the returned RealmValueType enums
     case RealmValueType.int:
       approximateAge = DateTime.now().year - anyValue.as<int>();
       break;

source/examples/generated/flutter/read_write_data_test.snippet.filter-nested-collections.dart

@@ -28,22 +28,19 @@ realm.write(() {
   ]);
 
   final teams = realm.all<Team>();
-  // Use [bracket notation] to query values at the specified path
+  // Use bracket notation to query values at the specified path
   final teamsWithHighPriorityEvents =
+      // Check any element at that path with [*]
       teams.query("eventLog[*].priority == 'high'");
   print(teamsWithHighPriorityEvents.length); // prints `2`
 
   final teamsWithMaintenanceEvents =
+      // Check for the first element at that path with [FIRST]
       teams.query("eventLog[*].type[FIRST] == 'maintenance'");
   print(teamsWithMaintenanceEvents.length); // prints `1`
 
-  // Use @keys to query map keys
-  final eventsWithComments =
-      teams.query("eventLog[*].@keys == 'comment'");
-  print(eventsWithComments.length); // prints `1`
-
-  // Use @type to query the collection type
   final teamsWithEventsAsLists =
+      // Check the collection type with @type 
       teams.query("eventLog[*].type.@type == 'list'");
   print(teamsWithEventsAsLists.length); // prints `2`
 });

source/sdk/flutter/crud/read.txt

@@ -214,8 +214,23 @@ Query Nested Collections of Mixed Data
 In Flutter SDK v2.0.0 and later, :ref:`RealmValue <flutter-realm-value>` 
 properties can contain collections (a list or map) of mixed data. These 
 collections can be nested within collections and can contain other 
-collections of mixed data. You can query these with dot notation, the 
-same way you would a normal collection. You can also use bracket notation to query a specific element in the collection (for example, ``[FIRST]``, ``[1]``, ``[LAST]``, or ``[*]``).
+collections of mixed data. 
+
+You can query these using the same RQL operators and syntax as you would for a  
+normal list or dictionary. Refer to the :ref:`rql` documentation for more
+information.  
+
+For nested collections, you can also use: 
+
+- Bracket notation, which provides additional collection query support: 
+   - ``[FIRST]`` and [``LAST``] - match the first or last elements within the collection
+   - ``[<int>]`` - match the element at the specific index 
+   - ``[*]`` - match any elements within the collection
+   - ``[SIZE]`` - match the collection length 
+- The ``@type`` operator, which has the following possible values: 
+   - ``array`` and ``list`` - match a list collection
+   - ``dictionary`` and ``object`` - match a map collection
+   - ``collection`` - matches a list or a map collection  
 
 .. literalinclude:: /examples/generated/flutter/read_write_data_test.snippet.filter-nested-collections.dart
    :language: dart

source/sdk/flutter/realm-database/model-data/data-types.txt

@@ -356,8 +356,9 @@ RealmValue
    - ``RealmValue.type`` is now an enum of ``RealmValueType`` instead of ``Type``.
    - ``RealmValue.uint8List`` is renamed to ``RealmValue.binary``. 
 
-   For more information on how to update an existing app from an earlier 
-   version to v2.0.0 or later, refer to :ref:`flutter-upgrade-v2`. 
+.. TODO: Add this back to above note once upgrade page is available
+.. For more information on how to update an existing app from an earlier 
+.. version to v2.0.0 or later, refer to :ref:`flutter-upgrade-v2`. 
 
 The `RealmValue <https://pub.dev/documentation/realm_common/latest/realm_common/RealmValue-class.html>`__
 data type is a mixed data type that can represent any other valid 
@@ -367,28 +368,37 @@ can represent a ``List<RealmValue>`` or ``Map<String, RealmValue>``.
 ``RealmValue`` is indexable, but cannot be a primary key. You can also create 
 collections of type ``RealmValue``. 
 
+Define a RealmValue Property
+````````````````````````````
+
+To define a property as ``RealmValue``, set its type in your object model. 
+
+.. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-value-model.dart
+   :language: dart
+
 .. note:: ``RealmValue`` Not Nullable But Can Contain Null Values
 
    When defining your Realm object schema, you cannot create a nullable ``RealmValue``.
    However, if you want a ``RealmValue`` property to contain a null value,
    you can use the special ``RealmValue.nullValue()`` property.
 
-To define a property as ``RealmValue``, set its type in your object model. 
-
-.. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-value-model.dart
-   :language: dart
+Create a RealmValue 
+```````````````````
 
 To add a ``RealmValue`` to a Realm object, call ``RealmValue.from()`` on the data or ``RealmValue.nullValue()`` to set a null value.
 
 .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-value-from.dart
    :language: dart
 
+
+
 .. _flutter-access-realm-value-type:
 
 Access RealmValue Data Type 
 ```````````````````````````
 
 .. versionchanged:: 2.0.0
+
    ``RealmValueType`` enum replaces ``RealmValue.type``.
    ``RealmValue.binary`` replaces  ``RealmValue.uint8List``.
 
@@ -399,16 +409,16 @@ To access the data stored in a ``RealmValue``, you can use:
 
 .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-value-value.dart
    :language: dart
-   :emphasize-lines: 3, 11
+   :emphasize-lines: 4, 13
 
 You can check the type of data currently stored in a ``RealmValue`` property by 
-accessing the type property. Starting with Flutter SDK v2.0.0, this returns a 
+accessing the ``type`` property. Starting with Flutter SDK v2.0.0, this returns a 
 ``RealmValueType`` enum. In earlier SDK versions, the SDK returned a 
 ``RealmValue.value.runtimeType``.
 
 .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-value-type.dart
    :language: dart
-   :emphasize-lines: 4
+   :emphasize-lines: 7, 10, 16
 
 .. _flutter-nested-collections-realm-value:
 
@@ -425,8 +435,8 @@ collections. They can also be :ref:`listened to for changes like a
 normal collection <flutter-realm-list-change-listener>`.
 
 You can leverage these nested collections to define unstructured 
-or variable data in your data model (for more information, refer to 
-:ref:`<flutter-model-unstructured-data>`). 
+or variable data in your data model. For more information, refer to 
+:ref:`<flutter-model-unstructured-data>`. 
 
 To create nested collections of mixed data in your app, define the mixed type 
 property in your data model the same way you would any other ``RealmValue`` type. 

source/sdk/flutter/realm-database/model-data/define-realm-object-schema.txt

@@ -268,8 +268,11 @@ data when modeling a variable event log object:
 
 .. literalinclude:: /examples/generated/flutter/define_realm_model_test.snippet.unstructured-data-model.dart
    :language: dart
+   :emphasize-lines: 9
+   :caption: EventLog data model 
 
 .. io-code-block::
+   :copyable: true
 
    .. input:: /examples/generated/flutter/define_realm_model_test.snippet.create-unstructured-data-example.dart
       :language: dart