diff --git a/docs/higher-order-functions.md b/docs/higher-order-functions.md
index 95ea8bd8..356171f6 100644
--- a/docs/higher-order-functions.md
+++ b/docs/higher-order-functions.md
@@ -7,7 +7,31 @@ sidebar_label: Higher Order Functions
 ## `$map()`
 __Signature:__ `$map(array, function)`
 
-Returns an array containing the results of applying the `function` parameter to each value in the `array` parameter.
+If the input argument is an array of 2 or more elements, returns an array containing the results of applying the `function` parameter to each value in the `array` parameter.
+
+```
+$map([1,2,3], function($v) { $v * 2 })
+```
+
+evaluates to
+
+```
+[ 2, 4, 6 ]
+```
+
+If the input argument is an array with 1 element, returns the single result of applying the `function` parameter to each value in the `array` parameter.
+
+```
+$map([2], function($v) { $v * 2 })
+```
+
+evaluates to
+
+```
+4
+```
+
+If the input argument is an empty array, returns nothing (represented in Javascript as `undefined`)
 
 The function that is supplied as the second parameter must have the following signature: