Data.Map and Haddock documentation
Jesper Louis Andersen
jlouis at mongers.org
Sun Nov 6 07:49:18 EST 2005
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
Data.Map> let a = insert 0 1 empty in insertWith (curry snd) 0 2 a
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 ;)
More information about the Libraries