Document Semigroup and Monoid instances (#1050)

Add Haddocks showing the definitions of (<>) and mempty.

containers/src/Data/IntMap/Internal.hs

@@ -440,12 +440,15 @@ infixl 9 !?,\\{-This comment teaches CPP correct behaviour -}
   Types
 --------------------------------------------------------------------}
 
+-- | @mempty@ = 'empty'
 instance Monoid (IntMap a) where
     mempty  = empty
     mconcat = unions
     mappend = (<>)
 
--- | @since 0.5.7
+-- | @(<>)@ = 'union'
+--
+-- @since 0.5.7
 instance Semigroup (IntMap a) where
     (<>)    = union
     stimes  = stimesIdempotentMonoid

containers/src/Data/IntSet/Internal.hs

@@ -326,12 +326,15 @@ type BitMap = Word
 deriving instance Lift IntSet
 #endif
 
+-- | @mempty@ = 'empty'
 instance Monoid IntSet where
     mempty  = empty
     mconcat = unions
     mappend = (<>)
 
--- | @since 0.5.7
+-- | @(<>)@ = 'union'
+--
+-- @since 0.5.7
 instance Semigroup IntSet where
     (<>)    = union
     stimes  = stimesIdempotentMonoid

containers/src/Data/Map/Internal.hs

@@ -464,11 +464,6 @@ m1 \\ m2 = difference m1 m2
   Size balanced trees.
 --------------------------------------------------------------------}
 -- | A Map from keys @k@ to values @a@.
---
--- The 'Semigroup' operation for 'Map' is 'union', which prefers
--- values from the left operand. If @m1@ maps a key @k@ to a value
--- @a1@, and @m2@ maps the same key to a different value @a2@, then
--- their union @m1 <> m2@ maps @k@ to @a1@.
 
 -- See Note: Order of constructors
 data Map k a  = Bin {-# UNPACK #-} !Size !k a !(Map k a) !(Map k a)
@@ -485,11 +480,15 @@ type role Map nominal representational
 deriving instance (Lift k, Lift a) => Lift (Map k a)
 #endif
 
+-- | @mempty@ = 'empty'
 instance (Ord k) => Monoid (Map k v) where
     mempty  = empty
     mconcat = unions
     mappend = (<>)
 
+-- | @(<>)@ = 'union'
+--
+-- @since 0.5.7
 instance (Ord k) => Semigroup (Map k v) where
     (<>)    = union
     stimes  = stimesIdempotentMonoid

containers/src/Data/Sequence/Internal.hs

@@ -1000,11 +1000,14 @@ instance Read1 Seq where
     (xs,t) <- readLst s
     pure (fromList xs, t)
 
+-- | @mempty@ = 'empty'
 instance Monoid (Seq a) where
     mempty = empty
     mappend = (Semigroup.<>)
 
--- | @since 0.5.7
+-- | @(<>)@ = '(><)'
+--
+-- @since 0.5.7
 instance Semigroup.Semigroup (Seq a) where
     (<>)    = (><)
     stimes = cycleNTimes . fromIntegral

containers/src/Data/Set/Internal.hs

@@ -303,12 +303,15 @@ type role Set nominal
 deriving instance Lift a => Lift (Set a)
 #endif
 
+-- | @mempty@ = 'empty'
 instance Ord a => Monoid (Set a) where
     mempty  = empty
     mconcat = unions
     mappend = (<>)
 
--- | @since 0.5.7
+-- | @(<>)@ = 'union'
+--
+-- @since 0.5.7
 instance Ord a => Semigroup (Set a) where
     (<>)    = union
     stimes  = stimesIdempotentMonoid