tweaked doc for the merge filter

doc/filters/merge.rst

@@ -1,12 +1,41 @@
 ``merge``
 =========
 
-The ``merge`` filter merges an array or a hash with the given value:
+The ``merge`` filter merges an array with the another array:
 
 .. code-block:: jinja
 
-    {% set items = { 'apple': 'fruit', 'orange': 'fruit' } %}
+    {% set values = [1, 2] %}
 
-    {% set items = items|merge({ 'peugeot': 'car' }) %}
+    {% set values = values|merge(['apple', 'orange']) %}
 
-    {# items now contains { 'apple': 'fruit', 'orange': 'fruit', 'peugeot': 'car' } #}
+    {# values now contains [1, 2, 'apple', 'orange'] #}
+
+New values are added at the end of the existing ones.
+
+The ``merge`` filter also works on hashes:
+
+.. code-block:: jinja
+
+    {% set items = { 'apple': 'fruit', 'orange': 'fruit', 'peugeot': 'unknown' } %}
+
+    {% set items = items|merge({ 'peugeot': 'car', 'renault': 'car' }) %}
+
+    {# items now contains { 'apple': 'fruit', 'orange': 'fruit', 'peugeot': 'car', 'renault': 'car' } #}
+
+For hashes, the merging process occurs on the keys: if the key does not
+already exist, it is added but if the key already exists, its value is
+overridden.
+
+.. tip::
+
+    If you want to ensure that some values are defined in an array (by given
+    default values), reverse the two elements in the call:
+
+    .. code-block:: jinja
+
+        {% set items = { 'apple': 'fruit', 'orange': 'fruit' } %}
+
+        {% set items = { 'apple': 'unknown' }|merge(items) %}
+
+        {# items now contains { 'apple': 'fruit', 'orange': 'fruit' } #}