doc: more details about iterators over dicts

doc/Expr.adoc

@@ -1419,7 +1419,8 @@ Lists and, soon, dictionaries, are implicit data-sources. The syntax for creatin
 *_iterator_* = "**$(**" _data-source_ "**)**" +
 _data-source_ = _explicit_ | _list-spec_ | _dict-spec_ | _custom-data-source_
 
-_explicit_ = _any-expr_ { "," _any-expr_ } +
+_explicit_ = _any-expr_ { "," _any-expr_ }
+
 _list-spec_ = _list_  _range-options_ +
 _list_ = "**[**" _any-expr_ { "," _any-expr_ } "**]**" +
 _range-options_ = [ "," _start-index_ [ "," _end-index_ [ "," _step_ ]]] +
@@ -1429,11 +1430,25 @@ _dict-spec_ = _dict_  _dict-options_ +
 _dict_ = "**{**" _key-value-pair_ { "," _key-value-pair_ } "**}**" +
 _key-value-pair_ = _scalar-value_ ":" _any-expr_ +
 _scalar-value_ = _string_ | _number_ | _boolean_ +
-_dict-options_ = [ "," _to-be-defined_ ]
+_dict-options_ = [ "," _sort-order_ [ "," _iter-mode_ ] ] +
+_sort-order_ = _asc-order_ | _desc-order_ | _no-sort_ | _default-order_ +
+_asc-order_ = "**asc**" | "**a**" +
+_desc-order_ = "**desc**" | "**d**" +
+_no-sort_ = "**none**" | "**nosort**" | "**no-sort**" | "**n**" +
+_default-order_ = "**default**" | "" +
+_iter-mode_ = _keys-iter_ | _values-iter_ | _items-iter_ | _default-iter_ +
+_keys-iter_ = "**key**" | "**keys**" | "**k**" +
+_values-iter_ = "**value**" | "**values**" | "**v**" +
+_items-iter_ = "**item**" | "**items**" | "**i**" +
+_default-iter_ = "**default**" | ""
 
 _custom-data-source_ = _dict_ having the key `next` whose value is a function that returns the next element of the collection and updates the state of the iterator.
 ====
 
+NOTE: Currently, _default-order_ is the same as _asc-order_. In the future, it will be possible to specify a custom sorting function to define the default order.
+
+NOTE: Currently, _default-iter_ is the same as _keys-iter_. In the future, it will be possible to specify a custom iteration function to define the default iteration mode.
+
 .Example: iterator over an explicit list of elements
 `>>>` [blue]`it = $("A", "B", "C")` +
 [green]`$(#3)` +
@@ -1512,7 +1527,7 @@ Named operators are operators that are identified by a name instead of a symbol.
 * *_.next_*: same as [blue]`{plusplus}`.
 * *_.current_*: same as [blue]`{star}`.
 * *_.reset_*: resets the state of the iterator to the initial state.
-* *_.count_*: returns the number of elements in the iterator, if it can be determined.
+* *_.count_*: returns the number of elements in the iterator already visited.
 * *_.index_*: returns the index of the current element in the iterator. Before the first use of the [blue]`{plusplus}` operator, it returns the error [red]_-1_.
 
 TIP: Iterators built on custom data-sources can provide additional named operators, depending on the functionality they want to expose. For example, an iterator over a list could provide a named operator called [blue]`.reverse` that returns the next element of the collection in reverse order.