updated doc for random function

CHANGELOG

@@ -10,6 +10,7 @@
  * added a date function to ease date comparison
  * fixed unary operators precedence
  * added recursive parsing support in the parser
+ * added string and integer handling for the random function
 
 * 1.5.1 (2012-01-05)
 

doc/functions/random.rst

@@ -4,8 +4,20 @@
 .. versionadded:: 1.5
     The random function was added in Twig 1.5.
 
-The ``random`` function returns a random item from a sequence:
+.. versionadded:: 1.6
+    String and integer handling was added in Twig 1.6.
+
+The ``random`` function returns a random value depending on the supplied paramter type:
+
+* a random item from a Traversable or array
+* a random character from a string 
+* a random integer between 0 and the integer parameter (inclusive)
 
 .. code-block:: jinja
 
-    {{ random(['apple', 'orange', 'citrus']) }}
+    {{ random(['apple', 'orange', 'citrus']) }} {# example output: orange #}
+    {{ random('ABC') }}                         {# example output: C #}
+    {{ random() }}                              {# example output: 15386094 (works as native PHP `mt_rand`_ function) #}
+    {{ random(5) }}                             {# example output: 3 #}
+
+.. _`mt_rand`: http://php.net/mt_rand