[HttpFoundation] Update documentation.

CHANGELOG-2.1.md

@@ -304,6 +304,9 @@ To get the diff between two versions, go to https://github.com/symfony/symfony/c
    attributes storage behaviour from 2.0.x (default).
  * Added `Symfony\Component\HttpFoundation\Attribute\NamespacedAttributeBag` for
    namespace session attributes.
+ * Flash API can stores messages in an array so there may be multiple messages
+   per flash type.  The old `Session` class API remains without BC break as it
+   will single messages as before.
 
 ### HttpKernel
 

UPGRADE-2.1.md

@@ -307,30 +307,31 @@ UPGRADE FROM 2.0 to 2.1
     Before:
 
     ```
-    {% if app.session.hasFlash('notice') %}
+    {% if app.session.flashbag.has('notice') %}
         <div class="flash-notice">
-            {{ app.session.flash('notice') }}
+            {{ app.session.flashbag.get('notice') }}
         </div>
     {% endif %}
     ```
-
     After:
 
     ```
-    {% if app.session.flashbag.has('notice') %}
+    {% for flashMessage in app.session.flashbag.get('notice') %}
         <div class="flash-notice">
-            {{ app.session.flashbag.get('notice') }}
+            {{ flashMessage }}
         </div>
-    {% endif %}
+    {% endfor %}
     ```
 
     You can process all flash messges in a single loop with:
 
     ```
-    {% for type, flashMessage in app.session.flashbag.all() %}
-        <div class="flash-{{ type }}">
-            {{ flashMessage }}
-        </div>
+    {% for type, flashMessages in app.session.flashbag.all() %}
+        {% for flashMessage in flashMessages) %}
+            <div class="flash-{{ type }}">
+                {{ flashMessage }}
+            </div>
+        {% endfor %}
     {% endfor %}
     ```