Update push and pull docs

docs/query-builder.md

@@ -454,13 +454,17 @@ Add one or multiple values to the items array.
 // Push the value to the matched documents
 DB::collection('users')
   ->where('name', 'John')
-    // Push a single value to the items array
-  ->push('items', 'boots'); // items: ['boots']
+  // Push a single value to the items array
+  ->push('items', 'boots');
+// Result:
+// items: ['boots']
 
 DB::collection('users')
   ->where('name', 'John')
-    // Push multiple values to the items array
-  ->push('items', ['hat', 'jeans']); // items: ['boots', 'hat', 'jeans']
+  // Push multiple values to the items array
+  ->push('items', ['hat', 'jeans']);
+// Result:
+// items: ['boots', 'hat', 'jeans']
 
 // Or
 
@@ -469,7 +473,8 @@ $user->push('items', 'boots');
 $user->push('items', ['hat', 'jeans']);
 ```
 
-To add an array to the messages array.
+To add an array as a value to the messages array. value arrays must be nested into a list array, otherwise they are
+interpreted as a list of scalar values.
 
 ```php
 DB::collection('users')
@@ -480,7 +485,11 @@ DB::collection('users')
           'from'    => 'Jane Doe',
           'message' => 'Hi John',
       ],
-  ]); // messages: [ ['from' => 'Jane Doe', 'message' => 'Hi John'] ]
+  ]);
+// Result:
+// messages: [
+//      { 'from' => 'Jane Doe', 'message' => 'Hi John' }
+//  ]
 
 // Or
 
@@ -497,11 +506,15 @@ If you **DON'T** want duplicate values, set the third parameter to `true`:
 ```php
 DB::collection('users')
   ->where('name', 'John')
-  ->push('items', 'boots'); // items: ['boots']
+  ->push('items', 'boots');
+// Result:
+// items: ['boots']
 
 DB::collection('users')
   ->where('name', 'John')
-  ->push('items', ['hat', 'boots', 'jeans'], true); // items: ['boots', 'hat', 'jeans']
+  ->push('items', ['hat', 'boots', 'jeans'], true);
+// Result:
+// items: ['boots', 'hat', 'jeans']
 
 // Or
 
@@ -510,18 +523,27 @@ $user->push('messages', [
         'from'    => 'Jane Doe',
         'message' => 'Hi John',
     ],
-]); // messages: [ ['from' => 'Jane Doe', 'message' => 'Hi John'] ]
+]);
+// Result:
+// messages: [
+//      { 'from' => 'Jane Doe', 'message' => 'Hi John' }
+//  ]
 
 $user->push('messages', [
     [
         'from'    => 'Jess Doe',
-        'message' => 'Hi John',
+        'message' => 'Hi',
     ],
     [
         'from'    => 'Jane Doe',
         'message' => 'Hi John',
     ],
-], true);  // messages: [ ['from' => 'Jane Doe', 'message' => 'Hi John'], ['from' => 'Jess Doe', 'message' => 'Hi John'] ]
+], true);
+// Result:
+// messages: [
+//      { 'from' => 'Jane Doe', 'message' => 'Hi John' }
+//      { 'from' => 'Jess Doe', 'message' => 'Hi' }
+//  ]
 ```
 
 **Pull**
@@ -533,18 +555,25 @@ Remove one or multiple values form items array.
 
 DB::collection('users')
   ->where('name', 'John')
-    // Pull a single value
-  ->pull('items', 'boots'); // items: ['hat', 'jeans']
+  ->pull('items', 'boots'); // Pull a single value
+// Result:
+// items: ['hat', 'jeans']
 
 // Or pull multiple values
 
-$user->pull('items', ['boots', 'jeans']);  // items: ['hat']
+$user->pull('items', ['boots', 'jeans']);
+// Result:
+// items: ['hat']
 ```
 
 Also, you can pull an array value from the messages array.
 
 ```php
-// messages: [ ['from' => 'Jane Doe', 'message' => 'Hi John'], ['from' => 'Jess Doe', 'message' => 'Hi John'] ]
+// Latest state:
+// messages: [
+//      { 'from' => 'Jane Doe', 'message' => 'Hi John' }
+//      { 'from' => 'Jess Doe', 'message' => 'Hi' }
+//  ]
 
 DB::collection('users')
   ->where('name', 'John')
@@ -554,7 +583,11 @@ DB::collection('users')
           'from' => 'Jane Doe',
           'message' => 'Hi John',
       ]
-  ]); // messages: [ ['from' => 'Jess Doe', 'message' => 'Hi John'] ]
+  ]);
+// Result:
+// messages: [
+//      { 'from' => 'Jess Doe', 'message' => 'Hi' }
+//  ]
 
 // Or pull multiple array
 
@@ -565,9 +598,11 @@ $user->pull('messages', [
     ],
     [
         'from' => 'Jess Doe',
-        'message' => 'Hi John',
+        'message' => 'Hi',
     ]
-]); // messages: [ ]
+]);
+// Result:
+// messages: [ ]
 ```
 
 **Unset**