Commit a90085bd authored by seraphime's avatar seraphime Committed by Ben Gamari

Add @since annotations to base instances

Add @since annotations to instances in `base`.

Test Plan:
 * ./validate  # some commets shouldn't break the build
 * review the annotations for absurdities.

Reviewers: ekmett, goldfire, RyanGlScott, austin, hvr, bgamari

Reviewed By: RyanGlScott, hvr, bgamari

Subscribers: thomie

Differential Revision: https://phabricator.haskell.org/D2277

GHC Trac Issues: #11767
parent 48e9a1f5
......@@ -66,13 +66,16 @@ import GHC.Show (Show)
newtype WrappedMonad m a = WrapMonad { unwrapMonad :: m a }
deriving (Generic, Generic1, Monad)
-- | @since 2.01
instance Monad m => Functor (WrappedMonad m) where
fmap f (WrapMonad v) = WrapMonad (liftM f v)
-- | @since 2.01
instance Monad m => Applicative (WrappedMonad m) where
pure = WrapMonad . pure
WrapMonad f <*> WrapMonad v = WrapMonad (f `ap` v)
-- | @since 2.01
instance MonadPlus m => Alternative (WrappedMonad m) where
empty = WrapMonad mzero
WrapMonad u <|> WrapMonad v = WrapMonad (u `mplus` v)
......@@ -80,13 +83,16 @@ instance MonadPlus m => Alternative (WrappedMonad m) where
newtype WrappedArrow a b c = WrapArrow { unwrapArrow :: a b c }
deriving (Generic, Generic1)
-- | @since 2.01
instance Arrow a => Functor (WrappedArrow a b) where
fmap f (WrapArrow a) = WrapArrow (a >>> arr f)
-- | @since 2.01
instance Arrow a => Applicative (WrappedArrow a b) where
pure x = WrapArrow (arr (const x))
WrapArrow f <*> WrapArrow v = WrapArrow (f &&& v >>> arr (uncurry id))
-- | @since 2.01
instance (ArrowZero a, ArrowPlus a) => Alternative (WrappedArrow a b) where
empty = WrapArrow zeroArrow
WrapArrow u <|> WrapArrow v = WrapArrow (u <+> v)
......@@ -100,6 +106,7 @@ newtype ZipList a = ZipList { getZipList :: [a] }
, Foldable, Generic, Generic1)
-- See Data.Traversable for Traversabel instance due to import loops
-- | @since 2.01
instance Applicative ZipList where
pure x = ZipList (repeat x)
ZipList fs <*> ZipList xs = ZipList (zipWith id fs xs)
......
......@@ -139,6 +139,7 @@ class Category a => Arrow a where
-- Ordinary functions are arrows.
-- | @since 2.01
instance Arrow (->) where
arr f = f
-- (f *** g) ~(x,y) = (f x, g y)
......@@ -148,10 +149,12 @@ instance Arrow (->) where
-- | Kleisli arrows of a monad.
newtype Kleisli m a b = Kleisli { runKleisli :: a -> m b }
-- | @since 3.0
instance Monad m => Category (Kleisli m) where
id = Kleisli return
(Kleisli f) . (Kleisli g) = Kleisli (\b -> g b >>= f)
-- | @since 2.01
instance Monad m => Arrow (Kleisli m) where
arr f = Kleisli (return . f)
first (Kleisli f) = Kleisli (\ ~(b,d) -> f b >>= \c -> return (c,d))
......@@ -180,6 +183,7 @@ f ^<< a = arr f <<< a
class Arrow a => ArrowZero a where
zeroArrow :: a b c
-- | @since 2.01
instance MonadPlus m => ArrowZero (Kleisli m) where
zeroArrow = Kleisli (\_ -> mzero)
......@@ -188,6 +192,7 @@ class ArrowZero a => ArrowPlus a where
-- | An associative operation with identity 'zeroArrow'.
(<+>) :: a b c -> a b c -> a b c
-- | @since 2.01
instance MonadPlus m => ArrowPlus (Kleisli m) where
Kleisli f <+> Kleisli g = Kleisli (\x -> f x `mplus` g x)
......@@ -269,12 +274,14 @@ class Arrow a => ArrowChoice a where
right f . right g = right (f . g)
#-}
-- | @since 2.01
instance ArrowChoice (->) where
left f = f +++ id
right f = id +++ f
f +++ g = (Left . f) ||| (Right . g)
(|||) = either
-- | @since 2.01
instance Monad m => ArrowChoice (Kleisli m) where
left f = f +++ arr id
right f = arr id +++ f
......@@ -295,9 +302,11 @@ instance Monad m => ArrowChoice (Kleisli m) where
class Arrow a => ArrowApply a where
app :: a (a b c, b) c
-- | @since 2.01
instance ArrowApply (->) where
app (f,x) = f x
-- | @since 2.01
instance Monad m => ArrowApply (Kleisli m) where
app = Kleisli (\(Kleisli f, x) -> f x)
......@@ -306,21 +315,26 @@ instance Monad m => ArrowApply (Kleisli m) where
newtype ArrowMonad a b = ArrowMonad (a () b)
-- | @since 4.6.0.0
instance Arrow a => Functor (ArrowMonad a) where
fmap f (ArrowMonad m) = ArrowMonad $ m >>> arr f
-- | @since 4.6.0.0
instance Arrow a => Applicative (ArrowMonad a) where
pure x = ArrowMonad (arr (const x))
ArrowMonad f <*> ArrowMonad x = ArrowMonad (f &&& x >>> arr (uncurry id))
-- | @since 2.01
instance ArrowApply a => Monad (ArrowMonad a) where
ArrowMonad m >>= f = ArrowMonad $
m >>> arr (\x -> let ArrowMonad h = f x in (h, ())) >>> app
-- | @since 4.6.0.0
instance ArrowPlus a => Alternative (ArrowMonad a) where
empty = ArrowMonad zeroArrow
ArrowMonad x <|> ArrowMonad y = ArrowMonad (x <+> y)
-- | @since 4.6.0.0
instance (ArrowApply a, ArrowPlus a) => MonadPlus (ArrowMonad a)
-- | Any instance of 'ArrowApply' can be made into an instance of
......@@ -361,12 +375,15 @@ leftApp f = arr ((\b -> (arr (\() -> b) >>> f >>> arr Left, ())) |||
class Arrow a => ArrowLoop a where
loop :: a (b,d) (c,d) -> a b c
-- | @since 2.01
instance ArrowLoop (->) where
loop f b = let (c,d) = f (b,d) in c
-- | Beware that for many monads (those for which the '>>=' operation
-- is strict) this instance will /not/ satisfy the right-tightening law
-- required by the 'ArrowLoop' class.
--
-- @since 2.01
instance MonadFix m => ArrowLoop (Kleisli m) where
loop (Kleisli f) = Kleisli (liftM fst . mfix . f')
where f' x y = f (x, snd y)
......@@ -46,14 +46,17 @@ class Category cat where
(p . q) . r = p . (q . r)
#-}
-- | @since 3.0
instance Category (->) where
id = GHC.Base.id
(.) = (GHC.Base..)
-- | @since 4.7.0.0
instance Category (:~:) where
id = Refl
Refl . Refl = Refl
-- | @since 4.7.0.0
instance Category Coercion where
id = Coercion
(.) Coercion = coerce
......
......@@ -140,6 +140,7 @@ import GHC.IO (interruptible)
-- | You need this when using 'catches'.
data Handler a = forall e . Exception e => Handler (e -> IO a)
-- | @since 4.6.0.0
instance Functor Handler where
fmap f (Handler h) = Handler (fmap f . h)
......
......@@ -299,9 +299,11 @@ bracketOnError before after thing =
-- source location of the pattern.
newtype PatternMatchFail = PatternMatchFail String
-- | @since 4.0
instance Show PatternMatchFail where
showsPrec _ (PatternMatchFail err) = showString err
-- | @since 4.0
instance Exception PatternMatchFail
-----
......@@ -313,9 +315,11 @@ instance Exception PatternMatchFail
-- location of the record selector.
newtype RecSelError = RecSelError String
-- | @since 4.0
instance Show RecSelError where
showsPrec _ (RecSelError err) = showString err
-- | @since 4.0
instance Exception RecSelError
-----
......@@ -325,9 +329,11 @@ instance Exception RecSelError
-- constructed.
newtype RecConError = RecConError String
-- | @since 4.0
instance Show RecConError where
showsPrec _ (RecConError err) = showString err
-- | @since 4.0
instance Exception RecConError
-----
......@@ -339,9 +345,11 @@ instance Exception RecConError
-- location of the record update.
newtype RecUpdError = RecUpdError String
-- | @since 4.0
instance Show RecUpdError where
showsPrec _ (RecUpdError err) = showString err
-- | @since 4.0
instance Exception RecUpdError
-----
......@@ -351,9 +359,11 @@ instance Exception RecUpdError
-- @String@ gives information about which method it was.
newtype NoMethodError = NoMethodError String
-- | @since 4.0
instance Show NoMethodError where
showsPrec _ (NoMethodError err) = showString err
-- | @since 4.0
instance Exception NoMethodError
-----
......@@ -365,9 +375,11 @@ instance Exception NoMethodError
-- @since 4.9.0.0
newtype TypeError = TypeError String
-- | @since 4.9.0.0
instance Show TypeError where
showsPrec _ (TypeError err) = showString err
-- | @since 4.9.0.0
instance Exception TypeError
-----
......@@ -378,9 +390,11 @@ instance Exception TypeError
-- guaranteed to terminate or not.
data NonTermination = NonTermination
-- | @since 4.0
instance Show NonTermination where
showsPrec _ NonTermination = showString "<<loop>>"
-- | @since 4.0
instance Exception NonTermination
-----
......@@ -389,9 +403,11 @@ instance Exception NonTermination
-- package, inside another call to @atomically@.
data NestedAtomically = NestedAtomically
-- | @since 4.0
instance Show NestedAtomically where
showsPrec _ NestedAtomically = showString "Control.Concurrent.STM.atomically was nested"
-- | @since 4.0
instance Exception NestedAtomically
-----
......
......@@ -67,12 +67,15 @@ class Monad m => MonadFail m where
fail :: String -> m a
-- | @since 4.9.0.0
instance MonadFail Maybe where
fail _ = Nothing
-- | @since 4.9.0.0
instance MonadFail [] where
{-# INLINE fail #-}
fail _ = []
-- | @since 4.9.0.0
instance MonadFail IO where
fail = failIO
......@@ -62,60 +62,76 @@ class (Monad m) => MonadFix m where
-- Instances of MonadFix for Prelude monads
-- | @since 2.01
instance MonadFix Maybe where
mfix f = let a = f (unJust a) in a
where unJust (Just x) = x
unJust Nothing = errorWithoutStackTrace "mfix Maybe: Nothing"
-- | @since 2.01
instance MonadFix [] where
mfix f = case fix (f . head) of
[] -> []
(x:_) -> x : mfix (tail . f)
-- | @since 2.01
instance MonadFix IO where
mfix = fixIO
-- | @since 2.01
instance MonadFix ((->) r) where
mfix f = \ r -> let a = f a r in a
-- | @since 4.3.0.0
instance MonadFix (Either e) where
mfix f = let a = f (unRight a) in a
where unRight (Right x) = x
unRight (Left _) = errorWithoutStackTrace "mfix Either: Left"
-- | @since 2.01
instance MonadFix (ST s) where
mfix = fixST
-- Instances of Data.Monoid wrappers
-- | @since 4.8.0.0
instance MonadFix Dual where
mfix f = Dual (fix (getDual . f))
-- | @since 4.8.0.0
instance MonadFix Sum where
mfix f = Sum (fix (getSum . f))
-- | @since 4.8.0.0
instance MonadFix Product where
mfix f = Product (fix (getProduct . f))
-- | @since 4.8.0.0
instance MonadFix First where
mfix f = First (mfix (getFirst . f))
-- | @since 4.8.0.0
instance MonadFix Last where
mfix f = Last (mfix (getLast . f))
-- | @since 4.8.0.0
instance MonadFix f => MonadFix (Alt f) where
mfix f = Alt (mfix (getAlt . f))
-- Instances for GHC.Generics
-- | @since 4.9.0.0
instance MonadFix Par1 where
mfix f = Par1 (fix (unPar1 . f))
-- | @since 4.9.0.0
instance MonadFix f => MonadFix (Rec1 f) where
mfix f = Rec1 (mfix (unRec1 . f))
-- | @since 4.9.0.0
instance MonadFix f => MonadFix (M1 i c f) where
mfix f = M1 (mfix (unM1. f))
-- | @since 4.9.0.0
instance (MonadFix f, MonadFix g) => MonadFix (f :*: g) where
mfix f = (mfix (fstP . f)) :*: (mfix (sndP . f))
where
......
......@@ -32,5 +32,6 @@ class (Monad m) => MonadIO m where
-- | Lift a computation from the 'IO' monad.
liftIO :: IO a -> m a
-- | @since 4.9.0.0
instance MonadIO IO where
liftIO = id
......@@ -62,6 +62,7 @@ import GHC.Base
newtype ST s a = ST (State s -> (a, State s))
data State s = S# (State# s)
-- | @since 2.01
instance Functor (ST s) where
fmap f m = ST $ \ s ->
let
......@@ -70,10 +71,12 @@ instance Functor (ST s) where
in
(f r,new_s)
-- | @since 2.01
instance Applicative (ST s) where
pure a = ST $ \ s -> (a,s)
(<*>) = ap
-- | @since 2.01
instance Monad (ST s) where
fail s = errorWithoutStackTrace s
......@@ -104,6 +107,7 @@ fixST m = ST (\ s ->
in
(r,s'))
-- | @since 2.01
instance MonadFix (ST s) where
mfix = fixST
......
......@@ -52,48 +52,62 @@ class Monad m => MonadZip m where
-- you can implement it more efficiently than the
-- above default code. See Trac #4370 comment by giorgidze
-- | @since 4.3.1.0
instance MonadZip [] where
mzip = zip
mzipWith = zipWith
munzip = unzip
-- | @since 4.8.0.0
instance MonadZip Dual where
-- Cannot use coerce, it's unsafe
mzipWith = liftM2
-- | @since 4.8.0.0
instance MonadZip Sum where
mzipWith = liftM2
-- | @since 4.8.0.0
instance MonadZip Product where
mzipWith = liftM2
-- | @since 4.8.0.0
instance MonadZip Maybe where
mzipWith = liftM2
-- | @since 4.8.0.0
instance MonadZip First where
mzipWith = liftM2
-- | @since 4.8.0.0
instance MonadZip Last where
mzipWith = liftM2
-- | @since 4.8.0.0
instance MonadZip f => MonadZip (Alt f) where
mzipWith f (Alt ma) (Alt mb) = Alt (mzipWith f ma mb)
-- | @since 4.9.0.0
instance MonadZip Proxy where
mzipWith _ _ _ = Proxy
-- Instances for GHC.Generics
-- | @since 4.9.0.0
instance MonadZip U1 where
mzipWith _ _ _ = U1
-- | @since 4.9.0.0
instance MonadZip Par1 where
mzipWith = liftM2
-- | @since 4.9.0.0
instance MonadZip f => MonadZip (Rec1 f) where
mzipWith f (Rec1 fa) (Rec1 fb) = Rec1 (mzipWith f fa fb)
-- | @since 4.9.0.0
instance MonadZip f => MonadZip (M1 i c f) where
mzipWith f (M1 fa) (M1 fb) = M1 (mzipWith f fa fb)
-- | @since 4.9.0.0
instance (MonadZip f, MonadZip g) => MonadZip (f :*: g) where
mzipWith f (x1 :*: y1) (x2 :*: y2) = mzipWith f x1 x2 :*: mzipWith f y1 y2
......@@ -75,31 +75,40 @@ class Bifunctor p where
second = bimap id
-- | @since 4.8.0.0
instance Bifunctor (,) where
bimap f g ~(a, b) = (f a, g b)
-- | @since 4.8.0.0
instance Bifunctor ((,,) x1) where
bimap f g ~(x1, a, b) = (x1, f a, g b)
-- | @since 4.8.0.0
instance Bifunctor ((,,,) x1 x2) where
bimap f g ~(x1, x2, a, b) = (x1, x2, f a, g b)
-- | @since 4.8.0.0
instance Bifunctor ((,,,,) x1 x2 x3) where
bimap f g ~(x1, x2, x3, a, b) = (x1, x2, x3, f a, g b)
-- | @since 4.8.0.0
instance Bifunctor ((,,,,,) x1 x2 x3 x4) where
bimap f g ~(x1, x2, x3, x4, a, b) = (x1, x2, x3, x4, f a, g b)
-- | @since 4.8.0.0
instance Bifunctor ((,,,,,,) x1 x2 x3 x4 x5) where
bimap f g ~(x1, x2, x3, x4, x5, a, b) = (x1, x2, x3, x4, x5, f a, g b)
-- | @since 4.8.0.0
instance Bifunctor Either where
bimap f _ (Left a) = Left (f a)
bimap _ g (Right b) = Right (g b)
-- | @since 4.8.0.0
instance Bifunctor Const where
bimap f _ (Const a) = Const (f a)
-- | @since 4.9.0.0
instance Bifunctor (K1 i) where
bimap f _ (K1 c) = K1 (f c)
......@@ -397,7 +397,9 @@ popCountDefault = go 0
{-# INLINABLE popCountDefault #-}
-- Interpret 'Bool' as 1-bit bit-field; @since 4.7.0.0
-- | Interpret 'Bool' as 1-bit bit-field
--
-- @since 4.7.0.0
instance Bits Bool where
(.&.) = (&&)
......@@ -427,11 +429,13 @@ instance Bits Bool where
popCount False = 0
popCount True = 1
-- | @since 4.7.0.0
instance FiniteBits Bool where
finiteBitSize _ = 1
countTrailingZeros x = if x then 0 else 1
countLeadingZeros x = if x then 0 else 1
-- | @since 2.01
instance Bits Int where
{-# INLINE shift #-}
{-# INLINE bit #-}
......@@ -468,11 +472,13 @@ instance Bits Int where
isSigned _ = True
-- | @since 4.6.0.0
instance FiniteBits Int where
finiteBitSize _ = WORD_SIZE_IN_BITS
countLeadingZeros (I# x#) = I# (word2Int# (clz# (int2Word# x#)))
countTrailingZeros (I# x#) = I# (word2Int# (ctz# (int2Word# x#)))
-- | @since 2.01
instance Bits Word where
{-# INLINE shift #-}
{-# INLINE bit #-}
......@@ -503,11 +509,13 @@ instance Bits Word where
bit = bitDefault
testBit = testBitDefault
-- | @since 4.6.0.0
instance FiniteBits Word where
finiteBitSize _ = WORD_SIZE_IN_BITS
countLeadingZeros (W# x#) = I# (word2Int# (clz# x#))
countTrailingZeros (W# x#) = I# (word2Int# (ctz# x#))
-- | @since 2.01
instance Bits Integer where
(.&.) = andInteger
(.|.) = orInteger
......
......@@ -115,6 +115,7 @@ phase (x:+y) = atan2 y x
-- -----------------------------------------------------------------------------
-- Instances of Complex
-- | @since 2.01
instance (RealFloat a) => Num (Complex a) where
{-# SPECIALISE instance Num (Complex Float) #-}
{-# SPECIALISE instance Num (Complex Double) #-}
......@@ -127,6 +128,7 @@ instance (RealFloat a) => Num (Complex a) where
signum z@(x:+y) = x/r :+ y/r where r = magnitude z
fromInteger n = fromInteger n :+ 0
-- | @since 2.01
instance (RealFloat a) => Fractional (Complex a) where
{-# SPECIALISE instance Fractional (Complex Float) #-}
{-# SPECIALISE instance Fractional (Complex Double) #-}
......@@ -138,6 +140,7 @@ instance (RealFloat a) => Fractional (Complex a) where
fromRational a = fromRational a :+ 0
-- | @since 2.01
instance (RealFloat a) => Floating (Complex a) where
{-# SPECIALISE instance Floating (Complex Float) #-}
{-# SPECIALISE instance Floating (Complex Double) #-}
......@@ -210,6 +213,7 @@ instance (RealFloat a) => Floating (Complex a) where
| otherwise = exp x - 1
{-# INLINE expm1 #-}
-- | @since 4.8.0.0
instance Storable a => Storable (Complex a) where
sizeOf a = 2 * sizeOf (realPart a)
alignment a = alignment (realPart a)
......@@ -223,9 +227,11 @@ instance Storable a => Storable (Complex a) where
poke q r
pokeElemOff q 1 i
-- | @since 4.9.0.0
instance Applicative Complex where
pure a = a :+ a
f :+ g <*> a :+ b = f a :+ g b
-- | @since 4.9.0.0
instance Monad Complex where
a :+ b >>= f = realPart (f a) :+ imagPart (f b)
......@@ -514,11 +514,14 @@ data Constr = Constr
, datatype :: DataType
}
-- | @since 4.0.0.0
instance Show Constr where
show = constring
-- | Equality of constructors
--
-- @since 4.0.0.0
instance Eq Constr where
c == c' = constrRep c == constrRep c'
......@@ -850,6 +853,7 @@ tyconModule x = let (a,b) = break ((==) '.') x
--