Add @since-annotations (#447)
authorSimon Jakobi <simon.jakobi@gmail.com>
Mon, 18 Dec 2017 19:13:06 +0000 (20:13 +0100)
committerDavid Feuer <David.Feuer@gmail.com>
Mon, 18 Dec 2017 19:13:06 +0000 (14:13 -0500)
* Add @since-annotations for v0.5.9.1

* Add @since-annotations for v0.5.8

* Add @since-annotations for v0.5.7

* Add @since-annotations for v0.5.6.2

* Add @since-annotations for v0.5.4

This change doesn't add annotations for the Typeable[0-2] instances that the
changelog claims were added in v0.5.4.0 as haddocks on Hackage show the same
instances for earlier versions like v0.4.0.0.

* Add @since-annotions for the Data.IntMap.Merge additions in v0.5.9

NB the change on the annotations for `merge` and `mergeA`.

* Add annotations for the contents of Data.Map.Merge.*

Data/Graph.hs
Data/IntMap/Internal.hs
Data/IntMap/Merge/Lazy.hs
Data/IntMap/Merge/Strict.hs
Data/IntSet/Internal.hs
Data/Map/Internal.hs
Data/Map/Merge/Lazy.hs
Data/Map/Merge/Strict.hs
Data/Sequence/Internal.hs
Data/Set/Internal.hs
Data/Tree.hs

index c7f5497..5e4c6b0 100644 (file)
@@ -117,40 +117,55 @@ data SCC vertex = AcyclicSCC vertex     -- ^ A single vertex that is not
                                         -- in any cycle.
                 | CyclicSCC  [vertex]   -- ^ A maximal set of mutually
                                         -- reachable vertices.
+#if __GLASGOW_HASKELL__ >= 802
+  deriving ( Eq   -- ^ @since 0.5.9
+           , Show -- ^ @since 0.5.9
+           , Read -- ^ @since 0.5.9
+           )
+#else
   deriving (Eq, Show, Read)
+#endif
 
 INSTANCE_TYPEABLE1(SCC)
 
 #ifdef __GLASGOW_HASKELL__
+-- | @since 0.5.9
 deriving instance Data vertex => Data (SCC vertex)
 #endif
 
 #if __GLASGOW_HASKELL__ >= 706
+-- | @since 0.5.9
 deriving instance Generic1 SCC
 #endif
 
 #if __GLASGOW_HASKELL__ >= 702
+-- | @since 0.5.9
 deriving instance Generic (SCC vertex)
 #endif
 
 #if MIN_VERSION_base(4,9,0)
+-- | @since 0.5.9
 instance Eq1 SCC where
   liftEq eq (AcyclicSCC v1) (AcyclicSCC v2) = eq v1 v2
   liftEq eq (CyclicSCC vs1) (CyclicSCC vs2) = liftEq eq vs1 vs2
   liftEq _ _ _ = False
+-- | @since 0.5.9
 instance Show1 SCC where
   liftShowsPrec sp _sl d (AcyclicSCC v) = showsUnaryWith sp "AcyclicSCC" d v
   liftShowsPrec _sp sl d (CyclicSCC vs) = showsUnaryWith (const sl) "CyclicSCC" d vs
+-- | @since 0.5.9
 instance Read1 SCC where
   liftReadsPrec rp rl = readsData $
     readsUnaryWith rp "AcyclicSCC" AcyclicSCC <>
     readsUnaryWith (const rl) "CyclicSCC" CyclicSCC
 #endif
 
+-- | @since 0.5.9
 instance F.Foldable SCC where
   foldr c n (AcyclicSCC v) = c v n
   foldr c n (CyclicSCC vs) = foldr c n vs
 
+-- | @since 0.5.9
 instance Traversable SCC where
   -- We treat the non-empty cyclic case specially to cut one
   -- fmap application.
@@ -163,6 +178,7 @@ instance NFData a => NFData (SCC a) where
     rnf (AcyclicSCC v) = rnf v
     rnf (CyclicSCC vs) = rnf vs
 
+-- | @since 0.5.4
 instance Functor SCC where
     fmap f (AcyclicSCC v) = AcyclicSCC (f v)
     fmap f (CyclicSCC vs) = CyclicSCC (fmap f vs)
index 6251a33..889ac82 100644 (file)
@@ -40,6 +40,8 @@
 --
 -- This defines the data structures and core (hidden) manipulations
 -- on representations.
+--
+-- @since 0.5.9
 -----------------------------------------------------------------------------
 
 -- [Note: INLINE bit fiddling]
@@ -398,6 +400,7 @@ instance Monoid (IntMap a) where
 #else
     mappend = (<>)
 
+-- | @since 0.5.7
 instance Semigroup (IntMap a) where
     (<>)    = union
     stimes  = stimesIdempotentMonoid
@@ -1333,17 +1336,20 @@ mergeWithKey' bin' f g1 g2 = go
 --
 -- A tactic of type @WhenMissing f k x z@ is an abstract representation
 -- of a function of type @Key -> x -> f (Maybe z)@.
+--
+-- @since 0.5.9
 
 data WhenMissing f x y = WhenMissing
   { missingSubtree :: IntMap x -> f (IntMap y)
   , missingKey :: Key -> x -> f (Maybe y)}
 
-
+-- | @since 0.5.9
 instance (Applicative f, Monad f) => Functor (WhenMissing f x) where
   fmap = mapWhenMissing
   {-# INLINE fmap #-}
 
 
+-- | @since 0.5.9
 instance (Applicative f, Monad f) => Category.Category (WhenMissing f)
   where
     id = preserveMissing
@@ -1358,6 +1364,8 @@ instance (Applicative f, Monad f) => Category.Category (WhenMissing f)
 
 
 -- | Equivalent to @ReaderT k (ReaderT x (MaybeT f))@.
+--
+-- @since 0.5.9
 instance (Applicative f, Monad f) => Applicative (WhenMissing f x) where
   pure x = mapMissing (\ _ _ -> x)
   f <*> g =
@@ -1371,6 +1379,8 @@ instance (Applicative f, Monad f) => Applicative (WhenMissing f x) where
 
 
 -- | Equivalent to @ReaderT k (ReaderT x (MaybeT f))@.
+--
+-- @since 0.5.9
 instance (Applicative f, Monad f) => Monad (WhenMissing f x) where
 #if !MIN_VERSION_base(4,8,0)
   return = pure
@@ -1385,6 +1395,8 @@ instance (Applicative f, Monad f) => Monad (WhenMissing f x) where
 
 
 -- | Map covariantly over a @'WhenMissing' f x@.
+--
+-- @since 0.5.9
 mapWhenMissing
   :: (Applicative f, Monad f)
   => (a -> b)
@@ -1422,6 +1434,8 @@ mapGentlyWhenMatched f t =
 
 
 -- | Map contravariantly over a @'WhenMissing' f _ x@.
+--
+-- @since 0.5.9
 lmapWhenMissing :: (b -> a) -> WhenMissing f a x -> WhenMissing f b x
 lmapWhenMissing f t = WhenMissing
   { missingSubtree = \m -> missingSubtree t (fmap f m)
@@ -1430,6 +1444,8 @@ lmapWhenMissing f t = WhenMissing
 
 
 -- | Map contravariantly over a @'WhenMatched' f _ y z@.
+--
+-- @since 0.5.9
 contramapFirstWhenMatched
   :: (b -> a)
   -> WhenMatched f a y z
@@ -1440,6 +1456,8 @@ contramapFirstWhenMatched f t =
 
 
 -- | Map contravariantly over a @'WhenMatched' f x _ z@.
+--
+-- @since 0.5.9
 contramapSecondWhenMatched
   :: (b -> a)
   -> WhenMatched f x a z
@@ -1465,6 +1483,8 @@ instance Applicative Identity where
 --
 -- A tactic of type @SimpleWhenMissing x z@ is an abstract
 -- representation of a function of type @Key -> x -> Maybe z@.
+--
+-- @since 0.5.9
 type SimpleWhenMissing = WhenMissing Identity
 
 
@@ -1473,12 +1493,16 @@ type SimpleWhenMissing = WhenMissing Identity
 --
 -- A tactic of type @WhenMatched f x y z@ is an abstract representation
 -- of a function of type @Key -> x -> y -> f (Maybe z)@.
+--
+-- @since 0.5.9
 newtype WhenMatched f x y z = WhenMatched
   { matchedKey :: Key -> x -> y -> f (Maybe z) }
 
 
 -- | Along with zipWithMaybeAMatched, witnesses the isomorphism
 -- between @WhenMatched f x y z@ and @Key -> x -> y -> f (Maybe z)@.
+--
+-- @since 0.5.9
 runWhenMatched :: WhenMatched f x y z -> Key -> x -> y -> f (Maybe z)
 runWhenMatched = matchedKey
 {-# INLINE runWhenMatched #-}
@@ -1486,16 +1510,20 @@ runWhenMatched = matchedKey
 
 -- | Along with traverseMaybeMissing, witnesses the isomorphism
 -- between @WhenMissing f x y@ and @Key -> x -> f (Maybe y)@.
+--
+-- @since 0.5.9
 runWhenMissing :: WhenMissing f x y -> Key-> x -> f (Maybe y)
 runWhenMissing = missingKey
 {-# INLINE runWhenMissing #-}
 
 
+-- | @since 0.5.9
 instance Functor f => Functor (WhenMatched f x y) where
   fmap = mapWhenMatched
   {-# INLINE fmap #-}
 
 
+-- | @since 0.5.9
 instance (Monad f, Applicative f) => Category.Category (WhenMatched f x)
   where
     id = zipWithMatched (\_ _ y -> y)
@@ -1510,6 +1538,8 @@ instance (Monad f, Applicative f) => Category.Category (WhenMatched f x)
 
 
 -- | Equivalent to @ReaderT Key (ReaderT x (ReaderT y (MaybeT f)))@
+--
+-- @since 0.5.9
 instance (Monad f, Applicative f) => Applicative (WhenMatched f x y) where
   pure x = zipWithMatched (\_ _ _ -> x)
   fs <*> xs =
@@ -1523,6 +1553,8 @@ instance (Monad f, Applicative f) => Applicative (WhenMatched f x y) where
 
 
 -- | Equivalent to @ReaderT Key (ReaderT x (ReaderT y (MaybeT f)))@
+--
+-- @since 0.5.9
 instance (Monad f, Applicative f) => Monad (WhenMatched f x y) where
 #if !MIN_VERSION_base(4,8,0)
   return = pure
@@ -1537,6 +1569,8 @@ instance (Monad f, Applicative f) => Monad (WhenMatched f x y) where
 
 
 -- | Map covariantly over a @'WhenMatched' f x y@.
+--
+-- @since 0.5.9
 mapWhenMatched
   :: Functor f
   => (a -> b)
@@ -1551,6 +1585,8 @@ mapWhenMatched f (WhenMatched g) =
 --
 -- A tactic of type @SimpleWhenMatched x y z@ is an abstract
 -- representation of a function of type @Key -> x -> y -> Maybe z@.
+--
+-- @since 0.5.9
 type SimpleWhenMatched = WhenMatched Identity
 
 
@@ -1560,6 +1596,8 @@ type SimpleWhenMatched = WhenMatched Identity
 -- > zipWithMatched
 -- >   :: (Key -> x -> y -> z)
 -- >   -> SimpleWhenMatched x y z
+--
+-- @since 0.5.9
 zipWithMatched
   :: Applicative f
   => (Key -> x -> y -> z)
@@ -1571,6 +1609,8 @@ zipWithMatched f = WhenMatched $ \ k x y -> pure . Just $ f k x y
 -- | When a key is found in both maps, apply a function to the key
 -- and values to produce an action and use its result in the merged
 -- map.
+--
+-- @since 0.5.9
 zipWithAMatched
   :: Applicative f
   => (Key -> x -> y -> f z)
@@ -1585,6 +1625,8 @@ zipWithAMatched f = WhenMatched $ \ k x y -> Just <$> f k x y
 -- > zipWithMaybeMatched
 -- >   :: (Key -> x -> y -> Maybe z)
 -- >   -> SimpleWhenMatched x y z
+--
+-- @since 0.5.9
 zipWithMaybeMatched
   :: Applicative f
   => (Key -> x -> y -> Maybe z)
@@ -1598,6 +1640,8 @@ zipWithMaybeMatched f = WhenMatched $ \ k x y -> pure $ f k x y
 -- result in the merged map.
 --
 -- This is the fundamental 'WhenMatched' tactic.
+--
+-- @since 0.5.9
 zipWithMaybeAMatched
   :: (Key -> x -> y -> f (Maybe z))
   -> WhenMatched f x y z
@@ -1613,6 +1657,8 @@ zipWithMaybeAMatched f = WhenMatched $ \ k x y -> f k x y
 -- prop> dropMissing = mapMaybeMissing (\_ _ -> Nothing)
 --
 -- but @dropMissing@ is much faster.
+--
+-- @since 0.5.9
 dropMissing :: Applicative f => WhenMissing f x y
 dropMissing = WhenMissing
   { missingSubtree = const (pure Nil)
@@ -1628,6 +1674,8 @@ dropMissing = WhenMissing
 -- prop> preserveMissing = Merge.Lazy.mapMaybeMissing (\_ x -> Just x)
 --
 -- but @preserveMissing@ is much faster.
+--
+-- @since 0.5.9
 preserveMissing :: Applicative f => WhenMissing f x x
 preserveMissing = WhenMissing
   { missingSubtree = pure
@@ -1642,6 +1690,8 @@ preserveMissing = WhenMissing
 -- prop> mapMissing f = mapMaybeMissing (\k x -> Just $ f k x)
 --
 -- but @mapMissing@ is somewhat faster.
+--
+-- @since 0.5.9
 mapMissing :: Applicative f => (Key -> x -> y) -> WhenMissing f x y
 mapMissing f = WhenMissing
   { missingSubtree = \m -> pure $! mapWithKey f m
@@ -1659,6 +1709,8 @@ mapMissing f = WhenMissing
 --
 -- but @mapMaybeMissing@ uses fewer unnecessary 'Applicative'
 -- operations.
+--
+-- @since 0.5.9
 mapMaybeMissing
   :: Applicative f => (Key -> x -> Maybe y) -> WhenMissing f x y
 mapMaybeMissing f = WhenMissing
@@ -1674,6 +1726,8 @@ mapMaybeMissing f = WhenMissing
 -- prop> filterMissing f = Merge.Lazy.mapMaybeMissing $ \k x -> guard (f k x) *> Just x
 --
 -- but this should be a little faster.
+--
+-- @since 0.5.9
 filterMissing
   :: Applicative f => (Key -> x -> Bool) -> WhenMissing f x x
 filterMissing f = WhenMissing
@@ -1689,6 +1743,8 @@ filterMissing f = WhenMissing
 -- >   \k x -> (\b -> guard b *> Just x) <$> f k x
 --
 -- but this should be a little faster.
+--
+-- @since 0.5.9
 filterAMissing
   :: Applicative f => (Key -> x -> f Bool) -> WhenMissing f x x
 filterAMissing f = WhenMissing
@@ -1713,6 +1769,8 @@ bool _ t True  = t
 
 -- | Traverse over the entries whose keys are missing from the other
 -- map.
+--
+-- @since 0.5.9
 traverseMissing
   :: Applicative f => (Key -> x -> f y) -> WhenMissing f x y
 traverseMissing f = WhenMissing
@@ -1725,6 +1783,8 @@ traverseMissing f = WhenMissing
 -- map, optionally producing values to put in the result. This is
 -- the most powerful 'WhenMissing' tactic, but others are usually
 -- more efficient.
+--
+-- @since 0.5.9
 traverseMaybeMissing
   :: Applicative f => (Key -> x -> f (Maybe y)) -> WhenMissing f x y
 traverseMaybeMissing f = WhenMissing
@@ -1812,7 +1872,7 @@ traverseMaybeWithKey f = go
 -- prop> symmetricDifference = merge diffPreserve diffPreserve (\ _ _ _ -> Nothing)
 -- prop> mapEachPiece f g h = merge (diffMapWithKey f) (diffMapWithKey g)
 --
--- @since 0.5.8
+-- @since 0.5.9
 merge
   :: SimpleWhenMissing a c -- ^ What to do with keys in @m1@ but not @m2@
   -> SimpleWhenMissing b c -- ^ What to do with keys in @m2@ but not @m1@
@@ -1887,7 +1947,7 @@ merge g1 g2 f m1 m2 =
 -- site. To prevent excessive inlining, you should generally only use
 -- 'mergeA' to define custom combining functions.
 --
--- @since 0.5.8
+-- @since 0.5.9
 mergeA
   :: (Applicative f)
   => WhenMissing f a c -- ^ What to do with keys in @m1@ but not @m2@
@@ -2752,6 +2812,8 @@ foldlWithKey' f z = \t ->      -- Use lambda t to be inlinable with two argument
 -- @'foldMapWithKey' f = 'Prelude.fold' . 'mapWithKey' f@
 --
 -- This can be an asymptotically faster than 'foldrWithKey' or 'foldlWithKey' for some monoids.
+--
+-- @since 0.5.4
 foldMapWithKey :: Monoid m => (Key -> a -> m) -> IntMap a -> m
 foldMapWithKey f = go
   where
@@ -2842,6 +2904,7 @@ fromSet f (IntSet.Tip kx bm) = buildTree f kx bm (IntSet.suffixBitMask + 1)
   Lists
 --------------------------------------------------------------------}
 #if __GLASGOW_HASKELL__ >= 708
+-- | @since 0.5.6.2
 instance GHCExts.IsList (IntMap a) where
   type Item (IntMap a) = (Key,a)
   fromList = fromList
@@ -3039,6 +3102,7 @@ nequal Nil Nil = False
 nequal _   _   = True
 
 #if MIN_VERSION_base(4,9,0)
+-- | @since 0.5.9
 instance Eq1 IntMap where
   liftEq eq (Bin p1 m1 l1 r1) (Bin p2 m2 l2 r2)
     = (m1 == m2) && (p1 == p2) && (liftEq eq l1 l2) && (liftEq eq r1 r2)
@@ -3056,6 +3120,7 @@ instance Ord a => Ord (IntMap a) where
     compare m1 m2 = compare (toList m1) (toList m2)
 
 #if MIN_VERSION_base(4,9,0)
+-- | @since 0.5.9
 instance Ord1 IntMap where
   liftCompare cmp m n =
     liftCompare (liftCompare cmp) (toList m) (toList n)
@@ -3083,6 +3148,7 @@ instance Show a => Show (IntMap a) where
     showString "fromList " . shows (toList m)
 
 #if MIN_VERSION_base(4,9,0)
+-- | @since 0.5.9
 instance Show1 IntMap where
     liftShowsPrec sp sl d m =
         showsUnaryWith (liftShowsPrec sp' sl') "fromList" d (toList m)
@@ -3110,6 +3176,7 @@ instance (Read e) => Read (IntMap e) where
 #endif
 
 #if MIN_VERSION_base(4,9,0)
+-- | @since 0.5.9
 instance Read1 IntMap where
     liftReadsPrec rp rl = readsData $
         readsUnaryWith (liftReadsPrec rp' rl') "fromList" fromList
index 5341da9..e271962 100644 (file)
@@ -43,6 +43,8 @@
 -- tactics are included because they are valid. However, they are
 -- inefficient in many cases and should usually be avoided. The instances
 -- for 'WhenMatched' tactics should not pose any major efficiency problems.
+--
+-- @since 0.5.9
 
 module Data.IntMap.Merge.Lazy (
     -- ** Simple merge tactic types
index e2b3e55..3f6f30f 100644 (file)
@@ -43,6 +43,8 @@
 -- tactics are included because they are valid. However, they are
 -- inefficient in many cases and should usually be avoided. The instances
 -- for 'WhenMatched' tactics should not pose any major efficiency problems.
+--
+-- @since 0.5.9
 
 module Data.IntMap.Merge.Strict (
     -- ** Simple merge tactic types
index 5b06c5f..e0e6c5c 100644 (file)
@@ -67,6 +67,8 @@
 -- This means that the operation can become linear in the number of
 -- elements with a maximum of /W/ -- the number of bits in an 'Int'
 -- (32 or 64).
+--
+-- @since 0.5.9
 -----------------------------------------------------------------------------
 
 -- [Note: INLINE bit fiddling]
@@ -271,6 +273,7 @@ instance Monoid IntSet where
 #else
     mappend = (<>)
 
+-- | @since 0.5.7
 instance Semigroup IntSet where
     (<>)    = union
     stimes  = stimesIdempotentMonoid
@@ -934,6 +937,7 @@ elems
   Lists
 --------------------------------------------------------------------}
 #if __GLASGOW_HASKELL__ >= 708
+-- | @since 0.5.6.2
 instance GHCExts.IsList IntSet where
   type Item IntSet = Key
   fromList = fromList
index cbb18fc..d46b6f9 100644 (file)
@@ -77,6 +77,8 @@
 --
 -- Operation comments contain the operation time complexity in
 -- the Big-O notation <http://en.wikipedia.org/wiki/Big_O_notation>.
+--
+-- @since 0.5.9
 -----------------------------------------------------------------------------
 
 -- [Note: Using INLINABLE]
@@ -430,6 +432,8 @@ infixl 9 !,!?,\\ --
 --
 -- prop> fromList [(5, 'a'), (3, 'b')] !? 1 == Nothing
 -- prop> fromList [(5, 'a'), (3, 'b')] !? 5 == Just 'a'
+--
+-- @since 0.5.9
 
 (!?) :: Ord k => Map k a -> k -> Maybe a
 (!?) m k = lookup k m
@@ -1487,6 +1491,8 @@ elemAt i (Bin _ kx x l r)
 -- @
 -- take n = 'fromDistinctAscList' . 'Prelude.take' n . 'toAscList'
 -- @
+--
+-- @since 0.5.8
 
 take :: Int -> Map k a -> Map k a
 take i m | i >= size m = m
@@ -1507,6 +1513,8 @@ take i0 m0 = go i0 m0
 -- @
 -- drop n = 'fromDistinctAscList' . 'Prelude.drop' n . 'toAscList'
 -- @
+--
+-- @since 0.5.8
 drop :: Int -> Map k a -> Map k a
 drop i m | i >= size m = Tip
 drop i0 m0 = go i0 m0
@@ -1525,6 +1533,8 @@ drop i0 m0 = go i0 m0
 -- @
 -- splitAt !n !xs = ('take' n xs, 'drop' n xs)
 -- @
+--
+-- @since 0.5.8
 splitAt :: Int -> Map k a -> (Map k a, Map k a)
 splitAt i0 m0
   | i0 >= size m0 = (m0, Tip)
@@ -2046,15 +2056,19 @@ instance Applicative Identity where
 --
 -- A tactic of type @ WhenMissing f k x z @ is an abstract representation
 -- of a function of type @ k -> x -> f (Maybe z) @.
+--
+-- @since 0.5.9
 
 data WhenMissing f k x y = WhenMissing
   { missingSubtree :: Map k x -> f (Map k y)
   , missingKey :: k -> x -> f (Maybe y)}
 
+-- | @since 0.5.9
 instance (Applicative f, Monad f) => Functor (WhenMissing f k x) where
   fmap = mapWhenMissing
   {-# INLINE fmap #-}
 
+-- | @since 0.5.9
 instance (Applicative f, Monad f)
          => Category.Category (WhenMissing f k) where
   id = preserveMissing
@@ -2067,6 +2081,8 @@ instance (Applicative f, Monad f)
   {-# INLINE (.) #-}
 
 -- | Equivalent to @ ReaderT k (ReaderT x (MaybeT f)) @.
+--
+-- @since 0.5.9
 instance (Applicative f, Monad f) => Applicative (WhenMissing f k x) where
   pure x = mapMissing (\ _ _ -> x)
   f <*> g = traverseMaybeMissing $ \k x -> do
@@ -2078,6 +2094,8 @@ instance (Applicative f, Monad f) => Applicative (WhenMissing f k x) where
   {-# INLINE (<*>) #-}
 
 -- | Equivalent to @ ReaderT k (ReaderT x (MaybeT f)) @.
+--
+-- @since 0.5.9
 instance (Applicative f, Monad f) => Monad (WhenMissing f k x) where
 #if !MIN_VERSION_base(4,8,0)
   return = pure
@@ -2090,6 +2108,8 @@ instance (Applicative f, Monad f) => Monad (WhenMissing f k x) where
   {-# INLINE (>>=) #-}
 
 -- | Map covariantly over a @'WhenMissing' f k x@.
+--
+-- @since 0.5.9
 mapWhenMissing :: (Applicative f, Monad f)
                => (a -> b)
                -> WhenMissing f k x a -> WhenMissing f k x b
@@ -2118,6 +2138,8 @@ mapGentlyWhenMatched f t = zipWithMaybeAMatched $
 {-# INLINE mapGentlyWhenMatched #-}
 
 -- | Map contravariantly over a @'WhenMissing' f k _ x@.
+--
+-- @since 0.5.9
 lmapWhenMissing :: (b -> a) -> WhenMissing f k a x -> WhenMissing f k b x
 lmapWhenMissing f t = WhenMissing
   { missingSubtree = \m -> missingSubtree t (fmap f m)
@@ -2125,6 +2147,8 @@ lmapWhenMissing f t = WhenMissing
 {-# INLINE lmapWhenMissing #-}
 
 -- | Map contravariantly over a @'WhenMatched' f k _ y z@.
+--
+-- @since 0.5.9
 contramapFirstWhenMatched :: (b -> a)
                           -> WhenMatched f k a y z
                           -> WhenMatched f k b y z
@@ -2133,6 +2157,8 @@ contramapFirstWhenMatched f t = WhenMatched $
 {-# INLINE contramapFirstWhenMatched #-}
 
 -- | Map contravariantly over a @'WhenMatched' f k x _ z@.
+--
+-- @since 0.5.9
 contramapSecondWhenMatched :: (b -> a)
                            -> WhenMatched f k x a z
                            -> WhenMatched f k x b z
@@ -2145,6 +2171,8 @@ contramapSecondWhenMatched f t = WhenMatched $
 --
 -- A tactic of type @ SimpleWhenMissing k x z @ is an abstract representation
 -- of a function of type @ k -> x -> Maybe z @.
+--
+-- @since 0.5.9
 type SimpleWhenMissing = WhenMissing Identity
 
 -- | A tactic for dealing with keys present in both
@@ -2152,25 +2180,33 @@ type SimpleWhenMissing = WhenMissing Identity
 --
 -- A tactic of type @ WhenMatched f k x y z @ is an abstract representation
 -- of a function of type @ k -> x -> y -> f (Maybe z) @.
+--
+-- @since 0.5.9
 newtype WhenMatched f k x y z = WhenMatched
   { matchedKey :: k -> x -> y -> f (Maybe z) }
 
 -- | Along with zipWithMaybeAMatched, witnesses the isomorphism between
 -- @WhenMatched f k x y z@ and @k -> x -> y -> f (Maybe z)@.
+--
+-- @since 0.5.9
 runWhenMatched :: WhenMatched f k x y z -> k -> x -> y -> f (Maybe z)
 runWhenMatched = matchedKey
 {-# INLINE runWhenMatched #-}
 
 -- | Along with traverseMaybeMissing, witnesses the isomorphism between
 -- @WhenMissing f k x y@ and @k -> x -> f (Maybe y)@.
+--
+-- @since 0.5.9
 runWhenMissing :: WhenMissing f k x y -> k -> x -> f (Maybe y)
 runWhenMissing = missingKey
 {-# INLINE runWhenMissing #-}
 
+-- | @since 0.5.9
 instance Functor f => Functor (WhenMatched f k x y) where
   fmap = mapWhenMatched
   {-# INLINE fmap #-}
 
+-- | @since 0.5.9
 instance (Monad f, Applicative f) => Category.Category (WhenMatched f k x) where
   id = zipWithMatched (\_ _ y -> y)
   f . g = zipWithMaybeAMatched $
@@ -2183,6 +2219,8 @@ instance (Monad f, Applicative f) => Category.Category (WhenMatched f k x) where
   {-# INLINE (.) #-}
 
 -- | Equivalent to @ ReaderT k (ReaderT x (ReaderT y (MaybeT f))) @
+--
+-- @since 0.5.9
 instance (Monad f, Applicative f) => Applicative (WhenMatched f k x y) where
   pure x = zipWithMatched (\_ _ _ -> x)
   fs <*> xs = zipWithMaybeAMatched $ \k x y -> do
@@ -2194,6 +2232,8 @@ instance (Monad f, Applicative f) => Applicative (WhenMatched f k x y) where
   {-# INLINE (<*>) #-}
 
 -- | Equivalent to @ ReaderT k (ReaderT x (ReaderT y (MaybeT f))) @
+--
+-- @since 0.5.9
 instance (Monad f, Applicative f) => Monad (WhenMatched f k x y) where
 #if !MIN_VERSION_base(4,8,0)
   return = pure
@@ -2206,6 +2246,8 @@ instance (Monad f, Applicative f) => Monad (WhenMatched f k x y) where
   {-# INLINE (>>=) #-}
 
 -- | Map covariantly over a @'WhenMatched' f k x y@.
+--
+-- @since 0.5.9
 mapWhenMatched :: Functor f
                => (a -> b)
                -> WhenMatched f k x y a
@@ -2217,6 +2259,8 @@ mapWhenMatched f (WhenMatched g) = WhenMatched $ \k x y -> fmap (fmap f) (g k x
 --
 -- A tactic of type @ SimpleWhenMatched k x y z @ is an abstract representation
 -- of a function of type @ k -> x -> y -> Maybe z @.
+--
+-- @since 0.5.9
 type SimpleWhenMatched = WhenMatched Identity
 
 -- | When a key is found in both maps, apply a function to the
@@ -2226,6 +2270,8 @@ type SimpleWhenMatched = WhenMatched Identity
 -- zipWithMatched :: (k -> x -> y -> z)
 --                -> SimpleWhenMatched k x y z
 -- @
+--
+-- @since 0.5.9
 zipWithMatched :: Applicative f
                => (k -> x -> y -> z)
                -> WhenMatched f k x y z
@@ -2234,6 +2280,8 @@ zipWithMatched f = WhenMatched $ \ k x y -> pure . Just $ f k x y
 
 -- | When a key is found in both maps, apply a function to the
 -- key and values to produce an action and use its result in the merged map.
+--
+-- @since 0.5.9
 zipWithAMatched :: Applicative f
                 => (k -> x -> y -> f z)
                 -> WhenMatched f k x y z
@@ -2247,6 +2295,8 @@ zipWithAMatched f = WhenMatched $ \ k x y -> Just <$> f k x y
 -- zipWithMaybeMatched :: (k -> x -> y -> Maybe z)
 --                     -> SimpleWhenMatched k x y z
 -- @
+--
+-- @since 0.5.9
 zipWithMaybeMatched :: Applicative f
                     => (k -> x -> y -> Maybe z)
                     -> WhenMatched f k x y z
@@ -2258,6 +2308,8 @@ zipWithMaybeMatched f = WhenMatched $ \ k x y -> pure $ f k x y
 -- the result in the merged map.
 --
 -- This is the fundamental 'WhenMatched' tactic.
+--
+-- @since 0.5.9
 zipWithMaybeAMatched :: (k -> x -> y -> f (Maybe z))
                      -> WhenMatched f k x y z
 zipWithMaybeAMatched f = WhenMatched $ \ k x y -> f k x y
@@ -2273,6 +2325,8 @@ zipWithMaybeAMatched f = WhenMatched $ \ k x y -> f k x y
 -- prop> dropMissing = mapMaybeMissing (\_ _ -> Nothing)
 --
 -- but @dropMissing@ is much faster.
+--
+-- @since 0.5.9
 dropMissing :: Applicative f => WhenMissing f k x y
 dropMissing = WhenMissing
   { missingSubtree = const (pure Tip)
@@ -2289,6 +2343,8 @@ dropMissing = WhenMissing
 -- prop> preserveMissing = Merge.Lazy.mapMaybeMissing (\_ x -> Just x)
 --
 -- but @preserveMissing@ is much faster.
+--
+-- @since 0.5.9
 preserveMissing :: Applicative f => WhenMissing f k x x
 preserveMissing = WhenMissing
   { missingSubtree = pure
@@ -2304,6 +2360,8 @@ preserveMissing = WhenMissing
 -- prop> mapMissing f = mapMaybeMissing (\k x -> Just $ f k x)
 --
 -- but @mapMissing@ is somewhat faster.
+--
+-- @since 0.5.9
 mapMissing :: Applicative f => (k -> x -> y) -> WhenMissing f k x y
 mapMissing f = WhenMissing
   { missingSubtree = \m -> pure $! mapWithKey f m
@@ -2321,6 +2379,8 @@ mapMissing f = WhenMissing
 -- prop> mapMaybeMissing f = traverseMaybeMissing (\k x -> pure (f k x))
 --
 -- but @mapMaybeMissing@ uses fewer unnecessary 'Applicative' operations.
+--
+-- @since 0.5.9
 mapMaybeMissing :: Applicative f => (k -> x -> Maybe y) -> WhenMissing f k x y
 mapMaybeMissing f = WhenMissing
   { missingSubtree = \m -> pure $! mapMaybeWithKey f m
@@ -2336,6 +2396,8 @@ mapMaybeMissing f = WhenMissing
 -- prop> filterMissing f = Merge.Lazy.mapMaybeMissing $ \k x -> guard (f k x) *> Just x
 --
 -- but this should be a little faster.
+--
+-- @since 0.5.9
 filterMissing :: Applicative f
               => (k -> x -> Bool) -> WhenMissing f k x x
 filterMissing f = WhenMissing
@@ -2352,6 +2414,8 @@ filterMissing f = WhenMissing
 -- @
 --
 -- but this should be a little faster.
+--
+-- @since 0.5.9
 filterAMissing :: Applicative f
               => (k -> x -> f Bool) -> WhenMissing f k x x
 filterAMissing f = WhenMissing
@@ -2365,6 +2429,8 @@ bool f _ False = f
 bool _ t True  = t
 
 -- | Traverse over the entries whose keys are missing from the other map.
+--
+-- @since 0.5.9
 traverseMissing :: Applicative f
                     => (k -> x -> f y) -> WhenMissing f k x y
 traverseMissing f = WhenMissing
@@ -2376,6 +2442,8 @@ traverseMissing f = WhenMissing
 -- optionally producing values to put in the result.
 -- This is the most powerful 'WhenMissing' tactic, but others are usually
 -- more efficient.
+--
+-- @since 0.5.9
 traverseMaybeMissing :: Applicative f
                       => (k -> x -> f (Maybe y)) -> WhenMissing f k x y
 traverseMaybeMissing f = WhenMissing
@@ -2452,7 +2520,7 @@ traverseMaybeMissing f = WhenMissing
 -- prop> symmetricDifference = merge diffPreserve diffPreserve (\ _ _ _ -> Nothing)
 -- prop> mapEachPiece f g h = merge (diffMapWithKey f) (diffMapWithKey g)
 --
--- @since 0.5.8
+-- @since 0.5.9
 merge :: Ord k
              => SimpleWhenMissing k a c -- ^ What to do with keys in @m1@ but not @m2@
              -> SimpleWhenMissing k b c -- ^ What to do with keys in @m2@ but not @m1@
@@ -2526,7 +2594,7 @@ merge g1 g2 f m1 m2 = runIdentity $
 -- site. To prevent excessive inlining, you should generally only use
 -- 'mergeA' to define custom combining functions.
 --
--- @since 0.5.8
+-- @since 0.5.9
 mergeA
   :: (Applicative f, Ord k)
   => WhenMissing f k a c -- ^ What to do with keys in @m1@ but not @m2@
@@ -2746,6 +2814,8 @@ filterWithKeyA p t@(Bin _ kx x l r) =
 -- takeWhileAntitone p = 'fromDistinctAscList' . 'Data.List.takeWhile' (p . fst) . 'toList'
 -- takeWhileAntitone p = 'filterWithKey' (\k _ -> p k)
 -- @
+--
+-- @since 0.5.8
 
 takeWhileAntitone :: (k -> Bool) -> Map k a -> Map k a
 takeWhileAntitone _ Tip = Tip
@@ -2761,6 +2831,8 @@ takeWhileAntitone p (Bin _ kx x l r)
 -- dropWhileAntitone p = 'fromDistinctAscList' . 'Data.List.dropWhile' (p . fst) . 'toList'
 -- dropWhileAntitone p = 'filterWithKey' (\k -> not (p k))
 -- @
+--
+-- @since 0.5.8
 
 dropWhileAntitone :: (k -> Bool) -> Map k a -> Map k a
 dropWhileAntitone _ Tip = Tip
@@ -2781,6 +2853,8 @@ dropWhileAntitone p (Bin _ kx x l r)
 -- at some /unspecified/ point where the predicate switches from holding to not
 -- holding (where the predicate is seen to hold before the first key and to fail
 -- after the last key).
+--
+-- @since 0.5.8
 
 spanAntitone :: (k -> Bool) -> Map k a -> (Map k a, Map k a)
 spanAntitone p0 m = toPair (go p0 m)
@@ -3170,6 +3244,8 @@ foldlWithKey' f z = go z
 -- @'foldMapWithKey' f = 'Prelude.fold' . 'mapWithKey' f@
 --
 -- This can be an asymptotically faster than 'foldrWithKey' or 'foldlWithKey' for some monoids.
+--
+-- @since 0.5.4
 foldMapWithKey :: Monoid m => (k -> a -> m) -> Map k a -> m
 foldMapWithKey f = go
   where
@@ -3234,6 +3310,7 @@ fromSet f (Set.Bin sz x l r) = Bin sz x (f x) (fromSet f l) (fromSet f r)
   use [foldlStrict] to reduce demand on the control-stack
 --------------------------------------------------------------------}
 #if __GLASGOW_HASKELL__ >= 708
+-- | @since 0.5.6.2
 instance (Ord k) => GHCExts.IsList (Map k v) where
   type Item (Map k v) = (k,v)
   fromList = fromList
@@ -3419,6 +3496,8 @@ fromAscList xs
 -- > fromDescList [(5,"a"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "b")]
 -- > valid (fromDescList [(5,"a"), (5,"b"), (3,"b")]) == True
 -- > valid (fromDescList [(5,"a"), (3,"b"), (5,"b")]) == False
+--
+-- @since 0.5.8
 
 fromDescList :: Eq k => [(k,a)] -> Map k a
 fromDescList xs = fromDistinctDescList (combineEq xs)
@@ -3458,6 +3537,8 @@ fromAscListWith f xs
 -- > fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "ba")]
 -- > valid (fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")]) == True
 -- > valid (fromDescListWith (++) [(5,"a"), (3,"b"), (5,"b")]) == False
+--
+-- @since 0.5.8
 
 fromDescListWith :: Eq k => (a -> a -> a) -> [(k,a)] -> Map k a
 fromDescListWith f xs
@@ -3554,6 +3635,8 @@ fromDistinctAscList ((kx0, x0) : xs0) = go (1::Int) (Bin 1 kx0 x0 Tip Tip) xs0
 -- > fromDistinctDescList [(5,"a"), (3,"b")] == fromList [(3, "b"), (5, "a")]
 -- > valid (fromDistinctDescList [(5,"a"), (3,"b")])          == True
 -- > valid (fromDistinctDescList [(5,"a"), (5,"b"), (3,"b")]) == False
+--
+-- @since 0.5.8
 
 -- For some reason, when 'singleton' is used in fromDistinctDescList or in
 -- create, it is not inlined, so we inline it manually.
@@ -3981,20 +4064,25 @@ instance (Ord k, Ord v) => Ord (Map k v) where
   Lifted instances
 --------------------------------------------------------------------}
 
+-- | @since 0.5.9
 instance Eq2 Map where
     liftEq2 eqk eqv m n =
         size m == size n && liftEq (liftEq2 eqk eqv) (toList m) (toList n)
 
+-- | @since 0.5.9
 instance Eq k => Eq1 (Map k) where
     liftEq = liftEq2 (==)
 
+-- | @since 0.5.9
 instance Ord2 Map where
     liftCompare2 cmpk cmpv m n =
         liftCompare (liftCompare2 cmpk cmpv) (toList m) (toList n)
 
+-- | @since 0.5.9
 instance Ord k => Ord1 (Map k) where
     liftCompare = liftCompare2 compare
 
+-- | @since 0.5.9
 instance Show2 Map where
     liftShowsPrec2 spk slk spv slv d m =
         showsUnaryWith (liftShowsPrec sp sl) "fromList" d (toList m)
@@ -4002,9 +4090,11 @@ instance Show2 Map where
         sp = liftShowsPrec2 spk slk spv slv
         sl = liftShowList2 spk slk spv slv
 
+-- | @since 0.5.9
 instance Show k => Show1 (Map k) where
     liftShowsPrec = liftShowsPrec2 showsPrec showList
 
+-- | @since 0.5.9
 instance (Ord k, Read k) => Read1 (Map k) where
     liftReadsPrec rp rl = readsData $
         readsUnaryWith (liftReadsPrec rp' rl') "fromList" fromList
@@ -4137,6 +4227,8 @@ INSTANCE_TYPEABLE2(Map)
 --  Note that the current implementation does not return more than three submaps,
 --  but you should not depend on this behaviour because it can change in the
 --  future without notice.
+--
+-- @since 0.5.4
 splitRoot :: Map k b -> [Map k b]
 splitRoot orig =
   case orig of
index 419bab0..5d16cf8 100644 (file)
@@ -43,6 +43,8 @@
 -- tactics are included because they are valid. However, they are
 -- inefficient in many cases and should usually be avoided. The instances
 -- for 'WhenMatched' tactics should not pose any major efficiency problems.
+--
+-- @since 0.5.9
 
 module Data.Map.Merge.Lazy (
     -- ** Simple merge tactic types
index 37ff55d..056da4b 100644 (file)
@@ -43,6 +43,8 @@
 -- tactics are included because they are valid. However, they are
 -- inefficient in many cases and should usually be avoided. The instances
 -- for 'WhenMatched' tactics should not pose any major efficiency problems.
+--
+-- @since 0.5.9
 
 module Data.Map.Merge.Strict (
     -- ** Simple merge tactic types
index 179fc93..28b6d76 100644 (file)
@@ -75,6 +75,7 @@
 -- '>>', particularly repeatedly and particularly in combination with
 -- 'replicate' or 'fromFunction'.
 --
+-- @since 0.5.9
 -----------------------------------------------------------------------------
 
 module Data.Sequence.Internal (
@@ -296,11 +297,15 @@ infixl 5 :|>
 #endif
 
 -- | A pattern synonym matching an empty sequence.
+--
+-- @since 0.5.8
 pattern Empty :: Seq a
 pattern Empty = Seq EmptyT
 
 -- | A pattern synonym viewing the front of a non-empty
 -- sequence.
+--
+-- @since 0.5.8
 pattern (:<|) :: a -> Seq a -> Seq a
 pattern x :<| xs <- (viewl -> x :< xs)
   where
@@ -308,6 +313,8 @@ pattern x :<| xs <- (viewl -> x :< xs)
 
 -- | A pattern synonym viewing the rear of a non-empty
 -- sequence.
+--
+-- @since 0.5.8
 pattern (:|>) :: Seq a -> a -> Seq a
 pattern xs :|> x <- (viewr -> xs :> x)
   where
@@ -435,6 +442,7 @@ instance Monad Seq where
       where add ys x = ys >< f x
     (>>) = (*>)
 
+-- | @since 0.5.11
 instance MonadFix Seq where
     mfix = mfixSeq
 
@@ -446,6 +454,7 @@ mfixSeq f = fromFunction (length (f err)) (\k -> fix (\xk -> f xk `index` k))
   where
     err = error "mfix for Data.Sequence.Seq applied to strict function"
 
+-- | @since 0.5.4
 instance Applicative Seq where
     pure = singleton
     xs *> ys = cycleNTimes (length xs) ys
@@ -763,6 +772,7 @@ instance MonadPlus Seq where
     mzero = empty
     mplus = (><)
 
+-- | @since 0.5.4
 instance Alternative Seq where
     empty = empty
     (<|>) = (><)
@@ -783,13 +793,16 @@ instance Show a => Show (Seq a) where
 #endif
 
 #if MIN_VERSION_base(4,9,0)
+-- | @since 0.5.9
 instance Show1 Seq where
   liftShowsPrec _shwsPrc shwList p xs = showParen (p > 10) $
         showString "fromList " . shwList (toList xs)
 
+-- | @since 0.5.9
 instance Eq1 Seq where
     liftEq eq xs ys = length xs == length ys && liftEq eq (toList xs) (toList ys)
 
+-- | @since 0.5.9
 instance Ord1 Seq where
     liftCompare cmp xs ys = liftCompare cmp (toList xs) (toList ys)
 #endif
@@ -810,6 +823,7 @@ instance Read a => Read (Seq a) where
 #endif
 
 #if MIN_VERSION_base(4,9,0)
+-- | @since 0.5.9
 instance Read1 Seq where
   liftReadsPrec _rp readLst p = readParen (p > 10) $ \r -> do
     ("fromList",s) <- lex r
@@ -822,6 +836,7 @@ instance Monoid (Seq a) where
     mappend = (><)
 
 #if MIN_VERSION_base(4,9,0)
+-- | @since 0.5.7
 instance Semigroup.Semigroup (Seq a) where
     (<>)    = (><)
 #endif
@@ -1687,9 +1702,11 @@ data ViewL a
 deriving instance Data a => Data (ViewL a)
 #endif
 #if __GLASGOW_HASKELL__ >= 706
+-- | @since 0.5.8
 deriving instance Generic1 ViewL
 #endif
 #if __GLASGOW_HASKELL__ >= 702
+-- | @since 0.5.8
 deriving instance Generic (ViewL a)
 #endif
 
@@ -1752,9 +1769,11 @@ data ViewR a
 deriving instance Data a => Data (ViewR a)
 #endif
 #if __GLASGOW_HASKELL__ >= 706
+-- | @since 0.5.8
 deriving instance Generic1 ViewR
 #endif
 #if __GLASGOW_HASKELL__ >= 702
+-- | @since 0.5.8
 deriving instance Generic (ViewR a)
 #endif
 
@@ -2031,6 +2050,8 @@ updateDigit v i (Four a b c d)
 -- can lead to poor performance and even memory leaks, because it does not
 -- force the new value before installing it in the sequence. 'adjust'' should
 -- usually be preferred.
+--
+-- @since 0.5.8
 adjust          :: (a -> a) -> Int -> Seq a -> Seq a
 adjust f i (Seq xs)
   -- See note on unsigned arithmetic in splitAt
@@ -2134,7 +2155,7 @@ adjustDigit f i (Four a b c d)
 -- insertAt 4 x (fromList [a,b,c,d]) = insertAt 10 x (fromList [a,b,c,d])
 --                                   = fromList [a,b,c,d,x]
 -- @
--- 
+--
 -- prop> insertAt i x xs = take i xs >< singleton x >< drop i xs
 --
 -- @since 0.5.8
@@ -2820,6 +2841,8 @@ valid.
 
 -- | /O(n)/. Convert a given sequence length and a function representing that
 -- sequence into a sequence.
+--
+-- @since 0.5.6.2
 fromFunction :: Int -> (Int -> a) -> Seq a
 fromFunction len f | len < 0 = error "Data.Sequence.fromFunction called with negative len"
                    | len == 0 = empty
@@ -2863,6 +2886,8 @@ fromFunction len f | len < 0 = error "Data.Sequence.fromFunction called with neg
 -- Note that the resulting sequence elements may be evaluated lazily (as on GHC),
 -- so you must force the entire structure to be sure that the original array
 -- can be garbage-collected.
+--
+-- @since 0.5.6.2
 fromArray :: Ix i => Array i a -> Seq a
 #ifdef __GLASGOW_HASKELL__
 fromArray a = fromFunction (GHC.Arr.numElements a) (GHC.Arr.unsafeAt a)
@@ -3301,7 +3326,7 @@ splitMiddleE i s spr pr ml (Node3 _ a b c) mr sf = case i of
     sprmla  = 1 + sprml
     sprmlab = sprmla + 1
 
-splitPrefixE :: Int -> Int -> Digit (Elem a) -> FingerTree (Node (Elem a)) -> Digit (Elem a) -> 
+splitPrefixE :: Int -> Int -> Digit (Elem a) -> FingerTree (Node (Elem a)) -> Digit (Elem a) ->
                     StrictPair (FingerTree (Elem a)) (FingerTree (Elem a))
 splitPrefixE !_i !s (One a) m sf = EmptyT :*: Deep s (One a) m sf
 splitPrefixE i s (Two a b) m sf = case i of
@@ -3317,7 +3342,7 @@ splitPrefixE i s (Four a b c d) m sf = case i of
   2 -> Deep 2 (One a) EmptyT (One b) :*: Deep (s - 2) (Two c d) m sf
   _ -> Deep 3 (Two a b) EmptyT (One c) :*: Deep (s - 3) (One d) m sf
 
-splitPrefixN :: Int -> Int -> Digit (Node a) -> FingerTree (Node (Node a)) -> Digit (Node a) -> 
+splitPrefixN :: Int -> Int -> Digit (Node a) -> FingerTree (Node (Node a)) -> Digit (Node a) ->
                     Split a
 splitPrefixN !_i !s (One a) m sf = Split EmptyT a (pullL (s - size a) m sf)
 splitPrefixN i s (Two a b) m sf
@@ -3389,6 +3414,8 @@ splitSuffixN i s pr m (Four a b c d)
 -- | /O(n)/. @chunksOf n xs@ splits @xs@ into chunks of size @n>0@.
 -- If @n@ does not divide the length of @xs@ evenly, then the last element
 -- of the result will be short.
+--
+-- @since 0.5.8
 chunksOf :: Int -> Seq a -> Seq (Seq a)
 chunksOf n xs | n <= 0 =
   if null xs
@@ -3897,6 +3924,7 @@ instance GHC.Exts.IsList (Seq a) where
 #endif
 
 #ifdef __GLASGOW_HASKELL__
+-- | @since 0.5.7
 instance IsString (Seq Char) where
     fromString = fromList
 #endif
index 7389643..a5cf9b8 100644 (file)
@@ -70,6 +70,8 @@
 -- /Warning/: The size of the set must not exceed @maxBound::Int@. Violation of
 -- this condition is not detected and if the size limit is exceeded, the
 -- behavior of the set is completely undefined.
+--
+-- @since 0.5.9
 -----------------------------------------------------------------------------
 
 -- [Note: Using INLINABLE]
@@ -284,6 +286,7 @@ instance Ord a => Monoid (Set a) where
 #else
     mappend = (<>)
 
+-- | @since 0.5.7
 instance Ord a => Semigroup (Set a) where
     (<>)    = union
     stimes  = stimesIdempotentMonoid
@@ -873,6 +876,7 @@ elems = toAscList
   Lists
 --------------------------------------------------------------------}
 #if __GLASGOW_HASKELL__ >= 708
+-- | @since 0.5.6.2
 instance (Ord a) => GHCExts.IsList (Set a) where
   type Item (Set a) = a
   fromList = fromList
@@ -983,6 +987,8 @@ fromAscList xs = fromDistinctAscList (combineEq xs)
 
 -- | /O(n)/. Build a set from a descending list in linear time.
 -- /The precondition (input list is descending) is not checked./
+--
+-- @since 0.5.8
 fromDescList :: Eq a => [a] -> Set a
 fromDescList xs = fromDistinctDescList (combineEq xs)
 #if __GLASGOW_HASKELL__
@@ -1030,6 +1036,8 @@ fromDistinctAscList (x0 : xs0) = go (1::Int) (Bin 1 x0 Tip Tip) xs0
 
 -- For some reason, when 'singleton' is used in fromDistinctDescList or in
 -- create, it is not inlined, so we inline it manually.
+--
+-- @since 0.5.8
 fromDistinctDescList :: [a] -> Set a
 fromDistinctDescList [] = Tip
 fromDistinctDescList (x0 : xs0) = go (1::Int) (Bin 1 x0 Tip Tip) xs0
@@ -1070,14 +1078,17 @@ instance Show a => Show (Set a) where
     showString "fromList " . shows (toList xs)
 
 #if MIN_VERSION_base(4,9,0)
+-- | @since 0.5.9
 instance Eq1 Set where
     liftEq eq m n =
         size m == size n && liftEq eq (toList m) (toList n)
 
+-- | @since 0.5.9
 instance Ord1 Set where
     liftCompare cmp m n =
         liftCompare cmp (toList m) (toList n)
 
+-- | @since 0.5.9
 instance Show1 Set where
     liftShowsPrec sp sl d m =
         showsUnaryWith (liftShowsPrec sp sl) "fromList" d (toList m)
@@ -1164,6 +1175,8 @@ splitMember x (Bin _ y l r)
 -- > findIndex 3 (fromList [5,3]) == 0
 -- > findIndex 5 (fromList [5,3]) == 1
 -- > findIndex 6 (fromList [5,3])    Error: element is not in the set
+--
+-- @since 0.5.4
 
 -- See Note: Type of local 'go' function
 findIndex :: Ord a => a -> Set a -> Int
@@ -1187,6 +1200,8 @@ findIndex = go 0
 -- > fromJust (lookupIndex 3 (fromList [5,3])) == 0
 -- > fromJust (lookupIndex 5 (fromList [5,3])) == 1
 -- > isJust   (lookupIndex 6 (fromList [5,3])) == False
+--
+-- @since 0.5.4
 
 -- See Note: Type of local 'go' function
 lookupIndex :: Ord a => a -> Set a -> Maybe Int
@@ -1209,6 +1224,8 @@ lookupIndex = go 0
 -- > elemAt 0 (fromList [5,3]) == 3
 -- > elemAt 1 (fromList [5,3]) == 5
 -- > elemAt 2 (fromList [5,3])    Error: index out of range
+--
+-- @since 0.5.4
 
 elemAt :: Int -> Set a -> a
 elemAt !_ Tip = error "Set.elemAt: index out of range"
@@ -1228,6 +1245,8 @@ elemAt i (Bin _ x l r)
 -- > deleteAt 1    (fromList [5,3]) == singleton 3
 -- > deleteAt 2    (fromList [5,3])    Error: index out of range
 -- > deleteAt (-1) (fromList [5,3])    Error: index out of range
+--
+-- @since 0.5.4
 
 deleteAt :: Int -> Set a -> Set a
 deleteAt !i t =
@@ -1246,6 +1265,8 @@ deleteAt !i t =
 -- @
 -- take n = 'fromDistinctAscList' . 'Prelude.take' n . 'toAscList'
 -- @
+--
+-- @since 0.5.8
 take :: Int -> Set a -> Set a
 take i m | i >= size m = m
 take i0 m0 = go i0 m0
@@ -1265,6 +1286,8 @@ take i0 m0 = go i0 m0
 -- @
 -- drop n = 'fromDistinctAscList' . 'Prelude.drop' n . 'toAscList'
 -- @
+--
+-- @since 0.5.8
 drop :: Int -> Set a -> Set a
 drop i m | i >= size m = Tip
 drop i0 m0 = go i0 m0
@@ -1307,6 +1330,8 @@ splitAt i0 m0
 -- takeWhileAntitone p = 'fromDistinctAscList' . 'Data.List.takeWhile' p . 'toList'
 -- takeWhileAntitone p = 'filter' p
 -- @
+--
+-- @since 0.5.8
 
 takeWhileAntitone :: (a -> Bool) -> Set a -> Set a
 takeWhileAntitone _ Tip = Tip
@@ -1322,6 +1347,8 @@ takeWhileAntitone p (Bin _ x l r)
 -- dropWhileAntitone p = 'fromDistinctAscList' . 'Data.List.dropWhile' p . 'toList'
 -- dropWhileAntitone p = 'filter' (not . p)
 -- @
+--
+-- @since 0.5.8
 
 dropWhileAntitone :: (a -> Bool) -> Set a -> Set a
 dropWhileAntitone _ Tip = Tip
@@ -1342,6 +1369,8 @@ dropWhileAntitone p (Bin _ x l r)
 -- at some /unspecified/ point where the predicate switches from holding to not
 -- holding (where the predicate is seen to hold before the first element and to fail
 -- after the last element).
+--
+-- @since 0.5.8
 
 spanAntitone :: (a -> Bool) -> Set a -> (Set a, Set a)
 spanAntitone p0 m = toPair (go p0 m)
@@ -1622,6 +1651,8 @@ bin x l r
 --  Note that the current implementation does not return more than three subsets,
 --  but you should not depend on this behaviour because it can change in the
 --  future without notice.
+--
+-- @since 0.5.4
 splitRoot :: Set a -> [Set a]
 splitRoot orig =
   case orig of
index 83e70e0..8d717d0 100644 (file)
@@ -84,7 +84,15 @@ data Tree a = Node {
         subForest :: Forest a   -- ^ zero or more child trees
     }
 #ifdef __GLASGOW_HASKELL__
-#if __GLASGOW_HASKELL__ >= 706
+#if __GLASGOW_HASKELL__ >= 802
+  deriving ( Eq
+           , Read
+           , Show
+           , Data
+           , Generic  -- ^ @since 0.5.8
+           , Generic1 -- ^ @since 0.5.8
+           )
+#elif __GLASGOW_HASKELL__ >= 706
   deriving (Eq, Read, Show, Data, Generic, Generic1)
 #elif __GLASGOW_HASKELL__ >= 702
   deriving (Eq, Read, Show, Data, Generic)
@@ -97,22 +105,26 @@ data Tree a = Node {
 type Forest a = [Tree a]
 
 #if MIN_VERSION_base(4,9,0)
+-- | @since 0.5.9
 instance Eq1 Tree where
   liftEq eq = leq
     where
       leq (Node a fr) (Node a' fr') = eq a a' && liftEq leq fr fr'
 
+-- | @since 0.5.9
 instance Ord1 Tree where
   liftCompare cmp = lcomp
     where
       lcomp (Node a fr) (Node a' fr') = cmp a a' <> liftCompare lcomp fr fr'
 
+-- | @since 0.5.9
 instance Show1 Tree where
   liftShowsPrec shw shwl p (Node a fr) = showParen (p > 10) $
         showString "Node {rootLabel = " . shw 0 a . showString ", " .
           showString "subForest = " . liftShowList shw shwl fr .
           showString "}"
 
+-- | @since 0.5.9
 instance Read1 Tree where
   liftReadsPrec rd rdl p = readParen (p > 10) $
     \s -> do
@@ -221,6 +233,8 @@ levels t =
         iterate (concatMap subForest) [t]
 
 -- | Catamorphism on trees.
+--
+-- @since 0.5.8
 foldTree :: (a -> [b] -> b) -> Tree a -> b
 foldTree f = go where
     go (Node x ts) = f x (map go ts)