In that case, you should add something like the above as a Rationale paragraph under the definition of comparator?.

Note, however, that there is no guarantee that  the trick works: a Scheme system that imports conflicting bindings may silently choose one of them.

 

I agree that the current descriptions do, when taken as a whole, say what I want them to say, but they do so in what is now an extremely confusing manner.  When it was possible to import mapping-map (to pick one at random) from either of two libraries, then it was reasonable to say in the first paragraph that associations were processed in an unspecified order, and then add that if you imported mapping-map from (srfi 146) you in fact got increasing key order, leaving it as implicit that if you imported it from (srfi 146 hash) you had no such guarantee.

But that is no longer the situation.  You can only import mapping-map from one of the two libraries, and so it always gives you the stronger behavior.  A user who is interested in what mapping-map does should not be told that it processes its associations in arbitrary order, and then immediately afterwards be told that it processes them in increasing key order (only if imported from (srfi 146), but where else could it be imported from?)  Rather, the user should be given the behavior of mapping-map, and then be told how hashmap-map differs from it.  This is what my suggested changes are intended to accomplish.

Alternatively, you could have a section on hashmaps, as SRFI 113 has a section on bags, collecting all the necessary differences in one place.  Either strategy is better than what you have now.

--