hashmap: migrate documentation from Documentation/technical into header

While at it, clarify the use of `key`, `keydata`, `entry_or_key` as well
as documenting the new data pointer for the compare function.

Rework the example.

Signed-off-by: Stefan Beller <[email protected]>
Signed-off-by: Junio C Hamano <[email protected]>

Author: stefanbeller