Update map.rst: return value

source/docs/functions/map.rst

@@ -3,7 +3,7 @@ map
 
 Description
 -----------
-Applies function to every item of an iterable and returns a list of the results.
+Applies function to every item of an iterable and returns an iterable of the results.
 
 Syntax
 ------
@@ -17,32 +17,34 @@ Syntax
 
 Return Value
 ------------
-list
+map object
 
 Time Complexity
 ------------
 #TODO
 
 Remarks
 -------
-If additional *iterable* arguments are passed, function must take that many arguments and is applied to the items from all iterables in parallel. If one *iterable* is shorter than another it is assumed to be extended with **None** items. If function is None, the identity function is assumed; if there are multiple arguments, map() returns a list consisting of tuples containing the corresponding items from all iterables (a kind of transpose operation). The *iterable* arguments may be a sequence or any iterable object; the result is always a list.
+If additional *iterable* arguments are passed, function must take that many arguments and is applied to the items from all iterables in parallel. If one *iterable* is shorter than another it is assumed to be extended with **None** items. If function is None, the identity function is assumed; if there are multiple arguments, map() returns a list consisting of tuples containing the corresponding items from all iterables (a kind of transpose operation). The *iterable* arguments may be a sequence or any iterable object; the result is always an iterable, a map object to be precise.
+
+The function will not be applied to the parameter iterable until the result iterable is called (transformed into list, popped first item, etc.). This can be done by calling e.g. next() or list() on the result (see examples).
 
 Example 1
 ---------
 >>> map(lambda x: x+x, (1, 2, 3))
-[2, 4, 6]
->>> map(lambda x, y: x/y, (1, 4, 9), (1, 2, 3))
+<map object at 0x0000014BC76494C0>
+>>> list(map(lambda x, y: x/y, (1, 4, 9), (1, 2, 3)))
 [1, 2, 3]
->>> map(lambda x, y, z: x+y+z, (1, 2, 3), (1, 4, 9), (1, 16, 27))
+>>> list(map(lambda x, y, z: x+y+z, (1, 2, 3), (1, 4, 9), (1, 16, 27)))
 [3, 22, 39]
 
 Example 2
 ---------
->>> map(None, [True, False])
+>>> list(map(None, [True, False]))
 [True, False]
->>> map(None, ['a', 'b'], [1, 2])
+>>> list(map(None, ['a', 'b'], [1, 2]))
 [('a', 1), ('b', 2)]
->>> map(None, ['a', 'b'], [1, 2, 3])
+>>> list(map(None, ['a', 'b'], [1, 2, 3]))
 [('a', 1), ('b', 2), (None, 3)]
 
 See Also