Bug 1478885 - Improve docs for mozilla::Hash{Set,Map}. r=luke

This patch does the following:

- Adds a bunch of useful high-level info at the top of the file, making the
  types easier to use for newcomers.

- Adds a comment to every Hash{Set,Map} method that lacked one.

- Tweaks lots of existing comments for clarity.

- Removes comments in Hash{Set,Map} referring to details within HashTable. That
  dependence is now covered in the top-level comment.

- Tweaks the signatures in hash policy classes to be more consistent.

--HG--
extra : rebase_source : ab9d6ae38b4b73e12151a228107ad3f3f12e36b3