Expr.doc: more details about the run() function from builtin iterator

doc/Expr.adoc

@@ -1583,7 +1583,33 @@ Module activation: +
 Syntax: +
 `{4sp}run(<iterator>, <operator>, <vars>) -> any`
 
-Iterates over the specified iterator and applies the specified operator to the current value of the iterator.
+where:
+[horizontal]
+iterator:: is any iterator.
+operator:: is a function that accepts two optional parameters: _index_ and _item_. 
+vars:: is a dictionary defining a set of variables that are used to initialize the local context of run() and that will be inherited by each call to the operator.
+
+TIP: Instead of using _index_ and _item_ parameter, the operator function can refere the two automatic variables `$_` and `$__` respectively.
+
+_run()_ iterates over the specified iterator and applies the specified operator to the current value of the iterator.
+It returns the value of the variable _status_ it defined, otherwise _nil_.
+
+In addition to the variables defined in vars, the local context includes the function _abort()_. The operator can call _abort()_ to terminate iterations.
+
+_abort()_ accepts the optional parameter _status_ used to change the value of of the variable of the same name and, therefore, of the value returned by _run()_.
+
+.Examples
+`>>>` [blue]`builtin "iterator"` [gray]__// enable the iterator builtin module__ +
+[green]`1` +
+`>>>` [blue]`run($(10..15), func(){status = $\_})` [gray]__// returns the last iteration's index__ +
+[green]`4` +
+`>>>` [blue]`run($(10..15), func(){status = $__})` [gray]_// returns the last iteration's item_ +
+[green]`14` +
+`>>>` [blue]`run($(1..5), func(index,item){ (index > 3) ? {abort()} :: {status = item} })` +
+[green]`4` +
+`>>>` [blue]`run($(1..5), func(index,item){ (index > 2) ? {abort("aborted")} :: {status = item} })` +
+[green]`aborted` 
+
 
 ==== Module "math.arith"
 Module activation: +