Data.Map and Haddock documentation

[Jesper Louis Andersen]

Hi Haskell hackers!

The library documentation I sit with for Data.Map misses some explanation:

insertWith :: Ord k => (a -> a -> a) -> k -> a -> Map k a -> Map k a

O(log n). Insert with a combining function.

Ok, we now have to guess about the exact semantics of this function. We 
expect that if k is not existing in the Map, the (k,a) pair is going to 
be inserted. If k is existing, the combining function will be called.

When the combining function is being called, we only have 50% chance of 
guessing the semantics. You could, with some correctness, postulate the 
documentation was 50% correct.

The following test is from hugs-2005Mar:

Data.Map> let a = insert 0 1 empty in insertWith (curry fst) 0 2 a
{0:=2}
Data.Map> let a = insert 0 1 empty in insertWith (curry snd) 0 2 a
{0:=1}

Aha!, so now we are able to make the documentation for the function better:

 > -- | /O(log n)/. Insert with a combining function. `insertWith f key
 > --   value mp` will insert the pair (key, value) into mp if key does
 > --   not exist in the map. If the key does exist, the function will
 > --   insert the value from the function call `f new_value old_value`.

Feel free to make my crude english better and to supply the same 
documentation for insertWithKey.

If this has already been done, ignore my message ;)