Add docs and doctests for methods

[Manishearth]

Would be nice if the methods had docs and doctests. A lot of this can be copied from std

[sffc]

What does insert return? From the code it calls or_insert, which means that it returns the value that is already in the map, and throws away the argument? This is different than other map-like APIs that return back the argument if the insertion failed.

[Manishearth]

It always returns the value inside the map, with no replacement, since that's the only operation that can work here. This should probably be documented better, and a version that returns (&V::Target, Option<V>) would be kinda nice to have as well