Re: [PATCH 1/5] hashmap: add usage documentation explaining hashmap_free[_entries]()

> From: Elijah Newren <newren@gmail.com>
> 
> The existence of hashmap_free() and hashmap_free_entries() confused me,
> and the docs weren't clear enough.  I had to consult other source code
> examples and the implementation.  Add a brief note to clarify,
> especially since hashmap_clear*() variants may be added in the future.

>  /*
> - * Frees a hashmap structure and allocated memory, leaves entries undisturbed
> + * Frees a hashmap structure and allocated memory for the table, but does not
> + * free the entries nor anything they point to.
> + *
> + * Usage note:
> + *
> + * Many callers will need to iterate over all entries and free the data each
> + * entry points to; in such a case, they can free the entry itself while at it.
> + * Thus, you might see:
> + *    hashmap_for_each_entry(map, hashmap_iter, e, hashmap_entry_name) {
> + *      free(e->somefield);
> + *      free(e);
> + *    }
> + *    hashmap_free(map);
> + * instead of
> + *    hashmap_for_each_entry(map, hashmap_iter, e, hashmap_entry_name) {
> + *      free(e->somefield);
> + *    }
> + *    hashmap_free_entries(map, struct my_entry_struct, hashmap_entry_name);
> + * to avoid the implicit extra loop over the entries.  However, if there are
> + * no special fields in your entry that need to be freed beyond the entry
> + * itself, it is probably simpler to avoid the explicit loop and just call
> + * hashmap_free_entries().