minor #9196 Documented the new behavior of getGroupSequence() method (javiereguiluz)

This PR was squashed before being merged into the 3.4 branch (closes #9196).

Discussion
----------

Documented the new behavior of getGroupSequence() method

This fixes #7166.

Commits
-------

b97fc0d Documented the new behavior of getGroupSequence() method

Author: javiereguiluz

validation/sequence_provider.rst

@@ -276,16 +276,22 @@ method, which should return an array of groups to use::
 
         public function getGroupSequence()
         {
-            $groups = array('User');
-
-            if ($this->isPremium()) {
-                $groups[] = 'Premium';
-            }
-
-            return $groups;
+            // when returning a simple array, if there's a violation in any group
+            // the rest of groups are not validated. E.g. if 'User' fails,
+            // 'Premium' and 'Api' are not validated:
+            return array('User', 'Premium', 'Api');
+
+            // when returning a nested array, all the groups included in each array
+            // are validated. E.g. if 'User' fails, 'Premium' is also validated
+            // (and you'll get its violations too) but 'Api' won't be validated:
+            return array(array('User', 'Premium'), 'Api');
         }
     }
 
+.. versionadded:: 3.2
+    The feature to return a nested array to get violations from all groups was
+    introduced in Symfony 3.2.
+
 At last, you have to notify the Validator component that your ``User`` class
 provides a sequence of groups to be validated: