merged branch pkruithof/patch-5 (PR #5781)

This PR was merged into the 2.1 branch.

Commits
-------

3e15d44 Documented removed _form_is_choice_group function

Discussion
----------

Documented removed `_form_is_choice_group` function

Also changed for-loop variables to match the current `form_div_layout.html.twig` code.

UPGRADE-2.1.md

@@ -536,25 +536,43 @@
 
   * In the choice field type's template, the `_form_is_choice_selected` method
     used to identify a selected choice has been replaced with the `selectedchoice`
-    filter.
+    filter. Similarly, the `_form_is_choice_group` method used to check if a 
+    choice is grouped has been removed and can be checked with the `iterable` 
+    test.
 
     Before:
 
     ```
     {% for choice, label in choices %}
-        <option value="{{ choice }}"{% if _form_is_choice_selected(form, choice) %} selected="selected"{% endif %}>
-            {{ label }}
-        </option>
+        {% if _form_is_choice_group(label) %}
+            <optgroup label="{{ choice|trans }}">
+                {% for nestedChoice, nestedLabel in label %}
+                    ... options tags ...
+                {% endfor %}
+            </optgroup>
+        {% else %}
+            <option value="{{ choice }}"{% if _form_is_choice_selected(form, choice) %} selected="selected"{% endif %}>
+                {{ label }}
+            </option>
+        {% endif %}
     {% endfor %}
     ```
 
     After:
 
     ```
-    {% for choice, label in choices %}
-        <option value="{{ choice.value }}"{% if choice is selectedchoice(choice.value) %} selected="selected"{% endif %}>
-            {{ label }}
-        </option>
+    {% for label, choice in choices %}
+        {% if choice is iterable %}
+            <optgroup label="{{ label|trans({}, translation_domain) }}">
+                {% for nestedChoice, nestedLabel in choice %}
+                    ... options tags ...
+                {% endfor %}
+            </optgroup>
+        {% else %}
+            <option value="{{ choice.value }}"{% if choice is selectedchoice(choice.value) %} selected="selected"{% endif %}>
+                {{ label }}
+            </option>
+        {% endif %}
     {% endfor %}
     ```