- no particular order, followed by a null pointer. After
- calling this function, only hsh_destroy() and hsh_count() may
- be applied to H. */
-void **
+ no particular order, followed by a null pointer.
+
+ After calling this function, only hsh_destroy() and
+ hsh_count() should be applied to H. hsh_first() and
+ hsh_next() could also be used, but you're better off just
+ iterating through the returned array.
+
+ This function is intended for use in situations where data
+ processing occurs in two phases. In the first phase, data is
+ added, removed, and searched for within a hash table. In the
+ second phase, the contents of the hash table are output and
+ the hash property itself is no longer of interest.
+
+ Use hsh_sort() instead, if the second phase wants data in
+ sorted order. Use hsh_data_copy() or hsh_sort_copy() instead,
+ if the second phase still needs to search the hash table. */
+void *const *