document the return-code semantic for the hashtable iterators

+ enforce applying the expected logic (proceed/stop/remove-and-proceed/remove-and-stop)