Commit 554aedab authored by Herbert Valerio Riedel's avatar Herbert Valerio Riedel 🕺

Convert `/Since: .../` to new `@since ...` syntax

Starting with Haddock 2.16 there's a new built-in support for since-annotations

Note: This exposes a bug in the `@since` implementation (see e.g. `Data.Bits`)
parent 45a9696c
......@@ -191,7 +191,7 @@ attribute will block all other threads.
-- This function is useful for informing the parent when a child
-- terminates, for example.
--
-- /Since: 4.6.0.0/
-- @since 4.6.0.0
forkFinally :: IO a -> (Either SomeException a -> IO ()) -> IO ThreadId
forkFinally action and_then =
mask $ \restore ->
......@@ -431,7 +431,7 @@ threadWaitWrite fd
-- is an IO action that can be used to deregister interest
-- in the file descriptor.
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
threadWaitReadSTM :: Fd -> IO (STM (), IO ())
threadWaitReadSTM fd
#ifdef mingw32_HOST_OS
......@@ -455,7 +455,7 @@ threadWaitReadSTM fd
-- is an IO action that can be used to deregister interest
-- in the file descriptor.
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
threadWaitWriteSTM :: Fd -> IO (STM (), IO ())
threadWaitWriteSTM fd
#ifdef mingw32_HOST_OS
......
......@@ -193,7 +193,7 @@ withMVar m io =
Like 'withMVar', but the @IO@ action in the second argument is executed
with asynchronous exceptions masked.
/Since: 4.7.0.0/
@since 4.7.0.0
-}
{-# INLINE withMVarMasked #-}
withMVarMasked :: MVar a -> (a -> IO b) -> IO b
......@@ -236,7 +236,7 @@ modifyMVar m io =
Like 'modifyMVar_', but the @IO@ action in the second argument is executed with
asynchronous exceptions masked.
/Since: 4.6.0.0/
@since 4.6.0.0
-}
{-# INLINE modifyMVarMasked_ #-}
modifyMVarMasked_ :: MVar a -> (a -> IO a) -> IO ()
......@@ -250,7 +250,7 @@ modifyMVarMasked_ m io =
Like 'modifyMVar', but the @IO@ action in the second argument is executed with
asynchronous exceptions masked.
/Since: 4.6.0.0/
@since 4.6.0.0
-}
{-# INLINE modifyMVarMasked #-}
modifyMVarMasked :: MVar a -> (a -> IO (a,b)) -> IO b
......@@ -268,7 +268,7 @@ addMVarFinalizer = GHC.MVar.addMVarFinalizer
-- | Make a 'Weak' pointer to an 'MVar', using the second argument as
-- a finalizer to run when 'MVar' is garbage-collected
--
-- /Since: 4.6.0.0/
-- @since 4.6.0.0
mkWeakMVar :: MVar a -> IO () -> IO (Weak (MVar a))
mkWeakMVar m@(MVar m#) f = IO $ \s ->
case mkWeak# m# m f s of (# s1, w #) -> (# s1, Weak w #)
......@@ -219,7 +219,7 @@ A typical use of 'tryJust' for recovery looks like this:
-- When called outside 'mask', or inside 'uninterruptibleMask', this
-- function has no effect.
--
-- /Since: 4.4.0.0/
-- @since 4.4.0.0
allowInterrupt :: IO ()
allowInterrupt = unsafeUnmask $ return ()
......
......@@ -199,7 +199,7 @@ infixl 4 <$!>
-- | Strict version of 'Data.Functor.<$>'.
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
(<$!>) :: Monad m => (a -> b) -> m a -> m b
{-# INLINE (<$!>) #-}
f <$!> m = do
......
......@@ -11,7 +11,7 @@
-- Stability : provisional
-- Portability : portable
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
----------------------------------------------------------------------------
module Data.Bifunctor
( Bifunctor(..)
......@@ -51,7 +51,7 @@ import Control.Applicative ( Const(..) )
-- 'second' (f '.' g) ≡ 'second' f '.' 'second' g
-- @
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
class Bifunctor p where
{-# MINIMAL bimap | first, second #-}
......
......@@ -156,7 +156,7 @@ class Eq a => Bits a where
-- implementation (which ought to be equivalent to 'zeroBits' for
-- types which possess a 0th bit).
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
zeroBits :: a
zeroBits = clearBit (bit 0) 0
......@@ -187,7 +187,7 @@ class Eq a => Bits a where
value of the argument is ignored. Returns Nothing
for types that do not have a fixed bitsize, like 'Integer'.
/Since: 4.7.0.0/
@since 4.7.0.0
-}
bitSizeMaybe :: a -> Maybe Int
......@@ -224,7 +224,7 @@ class Eq a => Bits a where
Defaults to 'shiftL' unless defined explicitly by an instance.
/Since: 4.5.0.0/ -}
@since 4.5.0.0 -}
unsafeShiftL :: a -> Int -> a
{-# INLINE unsafeShiftL #-}
x `unsafeShiftL` i = x `shiftL` i
......@@ -253,7 +253,7 @@ class Eq a => Bits a where
Defaults to 'shiftR' unless defined explicitly by an instance.
/Since: 4.5.0.0/ -}
@since 4.5.0.0 -}
unsafeShiftR :: a -> Int -> a
{-# INLINE unsafeShiftR #-}
x `unsafeShiftR` i = x `shiftR` i
......@@ -284,12 +284,12 @@ class Eq a => Bits a where
Can be implemented using `popCountDefault' if @a@ is also an
instance of 'Num'.
/Since: 4.5.0.0/ -}
@since 4.5.0.0 -}
popCount :: a -> Int
-- |The 'FiniteBits' class denotes types with a finite, fixed number of bits.
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
class Bits b => FiniteBits b where
-- | Return the number of bits in the type of the argument.
-- The actual value of the argument is ignored. Moreover, 'finiteBitSize'
......@@ -300,7 +300,7 @@ class Bits b => FiniteBits b where
-- 'bitSizeMaybe' = 'Just' . 'finiteBitSize'
-- @
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
finiteBitSize :: b -> Int
-- | Count number of zero bits preceding the most significant set bit.
......@@ -320,7 +320,7 @@ class Bits b => FiniteBits b where
-- integral types are implemented using CPU specific machine
-- instructions.
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
countLeadingZeros :: b -> Int
countLeadingZeros x = (w-1) - go (w-1)
where
......@@ -350,7 +350,7 @@ class Bits b => FiniteBits b where
-- integral types are implemented using CPU specific machine
-- instructions.
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
countTrailingZeros :: b -> Int
countTrailingZeros x = go 0
where
......@@ -369,7 +369,7 @@ class Bits b => FiniteBits b where
--
-- Note that: @bitDefault i = 1 `shiftL` i@
--
-- /Since: 4.6.0.0/
-- @since 4.6.0.0
bitDefault :: (Bits a, Num a) => Int -> a
bitDefault = \i -> 1 `shiftL` i
{-# INLINE bitDefault #-}
......@@ -378,7 +378,7 @@ bitDefault = \i -> 1 `shiftL` i
--
-- Note that: @testBitDefault x i = (x .&. bit i) /= 0@
--
-- /Since: 4.6.0.0/
-- @since 4.6.0.0
testBitDefault :: (Bits a, Num a) => a -> Int -> Bool
testBitDefault = \x i -> (x .&. bit i) /= 0
{-# INLINE testBitDefault #-}
......@@ -388,7 +388,7 @@ testBitDefault = \x i -> (x .&. bit i) /= 0
-- This implementation is intentionally naive. Instances are expected to provide
-- an optimized implementation for their size.
--
-- /Since: 4.6.0.0/
-- @since 4.6.0.0
popCountDefault :: (Bits a, Num a) => a -> Int
popCountDefault = go 0
where
......@@ -397,7 +397,7 @@ 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
(.&.) = (&&)
......@@ -557,7 +557,7 @@ instance Bits Integer where
-- 'fromIntegral', which is itself optimized with rules for @base@ types but may
-- go through 'Integer' for some type pairs.)
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
toIntegralSized :: (Integral a, Integral b, Bits a, Bits b) => a -> Maybe b
toIntegralSized x -- See Note [toIntegralSized optimization]
......
......@@ -35,7 +35,7 @@ import GHC.Base
-- think of it as an if-then-else construct with its arguments
-- reordered.
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
--
-- ==== __Examples__
--
......
......@@ -16,7 +16,7 @@
-- More in-depth information can be found on the
-- <https://ghc.haskell.org/trac/ghc/wiki/Roles Roles wiki page>
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
-----------------------------------------------------------------------------
module Data.Coerce
......
......@@ -218,7 +218,7 @@ partitionEithers = foldr (either left right) ([],[])
-- | Return `True` if the given value is a `Left`-value, `False` otherwise.
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
--
-- ==== __Examples__
--
......@@ -250,7 +250,7 @@ isLeft (Right _) = False
-- | Return `True` if the given value is a `Right`-value, `False` otherwise.
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
--
-- ==== __Examples__
--
......
......@@ -58,7 +58,7 @@ mod' n d = n - (fromInteger f) * d where
f = div' n d
-- | The type parameter should be an instance of 'HasResolution'.
newtype Fixed a = MkFixed Integer -- ^ /Since: 4.7.0.0/
newtype Fixed a = MkFixed Integer -- ^ @since 4.7.0.0
deriving (Eq,Ord)
-- We do this because the automatically derived Data instance requires (Data a) context.
......
......@@ -95,6 +95,6 @@ on :: (b -> b -> c) -> (a -> b) -> a -> a -> c
-- convenience. Its precedence is one higher than that of the forward
-- application operator '$', which allows '&' to be nested in '$'.
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
(&) :: a -> (a -> b) -> b
x & f = f x
......@@ -67,7 +67,7 @@ infixl 4 $>
-- | Flipped version of '<$'.
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
--
-- ==== __Examples__
--
......
......@@ -25,7 +25,7 @@
-- applying the transformer to 'Identity'. For example, @State s@
-- is an abbreviation for @StateT s 'Identity'@.
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
-----------------------------------------------------------------------------
module Data.Functor.Identity (
......@@ -38,7 +38,7 @@ import Data.Foldable
-- | Identity functor and monad. (a non-strict monad)
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
newtype Identity a = Identity { runIdentity :: a }
deriving (Eq, Ord, Traversable)
......
......@@ -71,7 +71,7 @@ modifyIORef ref f = readIORef ref >>= writeIORef ref . f
-- |Strict version of 'modifyIORef'
--
-- /Since: 4.6.0.0/
-- @since 4.6.0.0
modifyIORef' :: IORef a -> (a -> a) -> IO ()
modifyIORef' ref f = do
x <- readIORef ref
......@@ -103,7 +103,7 @@ atomicModifyIORef = GHC.IORef.atomicModifyIORef
-- | Strict version of 'atomicModifyIORef'. This forces both the value stored
-- in the 'IORef' as well as the value returned.
--
-- /Since: 4.6.0.0/
-- @since 4.6.0.0
atomicModifyIORef' :: IORef a -> (a -> (a,b)) -> IO b
atomicModifyIORef' ref f = do
b <- atomicModifyIORef ref $ \a ->
......@@ -114,7 +114,7 @@ atomicModifyIORef' ref f = do
-- | Variant of 'writeIORef' with the \"barrier to reordering\" property that
-- 'atomicModifyIORef' has.
--
-- /Since: 4.6.0.0/
-- @since 4.6.0.0
atomicWriteIORef :: IORef a -> a -> IO ()
atomicWriteIORef ref a = do
x <- atomicModifyIORef ref (\_ -> (a, ()))
......
......@@ -224,7 +224,7 @@ import GHC.Base ( Bool(..), Eq((==)), otherwise )
--
-- @'isSubsequenceOf' x y@ is equivalent to @'elem' x ('subsequences' y)@.
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
--
-- ==== __Examples__
--
......
......@@ -60,7 +60,7 @@ infixr 6 <>
-- | An infix synonym for 'mappend'.
--
-- /Since: 4.5.0.0/
-- @since 4.5.0.0
(<>) :: Monoid m => m -> m -> m
(<>) = mappend
{-# INLINE (<>) #-}
......@@ -177,7 +177,7 @@ instance Monoid (Last a) where
-- | Monoid under '<|>'.
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
newtype Alt f a = Alt {getAlt :: f a}
deriving (Generic, Generic1, Read, Show, Eq, Ord, Num, Enum,
Monad, MonadPlus, Applicative, Alternative, Functor)
......
......@@ -231,7 +231,7 @@ infix 5 \\ -- comment to fool cpp: https://www.haskell.org/ghc/docs/latest/html/
-- > dropWhileEnd isSpace "foo bar" == "foo bar"
-- > dropWhileEnd isSpace ("foo\n" ++ undefined) == "foo" ++ undefined
--
-- /Since: 4.5.0.0/
-- @since 4.5.0.0
dropWhileEnd :: (a -> Bool) -> [a] -> [a]
dropWhileEnd p = foldr (\x xs -> if p x && null xs then [] else x : xs) []
......@@ -974,7 +974,7 @@ rqpart cmp x (y:ys) rle rgt r =
-- input list. This is called the decorate-sort-undecorate paradigm, or
-- Schwartzian transform.
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
sortOn :: Ord b => (a -> b) -> [a] -> [a]
sortOn f =
map snd . sortBy (comparing fst) . map (\x -> let y = f x in y `seq` (y, x))
......
......@@ -45,7 +45,7 @@ comparing p x y = compare (p x) (p y)
--
-- Provides 'Show' and 'Read' instances (/since: 4.7.0.0/).
--
-- /Since: 4.6.0.0/
-- @since 4.6.0.0
newtype Down a = Down a deriving (Eq, Show, Read)
instance Ord a => Ord (Down a) where
......
......@@ -13,7 +13,7 @@
--
-- Definition of a Proxy type (poly-kinded in GHC)
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
-----------------------------------------------------------------------------
module Data.Proxy
......
......@@ -46,7 +46,7 @@ modifySTRef ref f = writeSTRef ref . f =<< readSTRef ref
-- | Strict version of 'modifySTRef'
--
-- /Since: 4.6.0.0/
-- @since 4.6.0.0
modifySTRef' :: STRef s a -> (a -> a) -> ST s ()
modifySTRef' ref f = do
x <- readSTRef ref
......
......@@ -13,7 +13,7 @@
--
-- Basic operations on type-level Booleans.
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
-----------------------------------------------------------------------------
module Data.Type.Bool (
......
......@@ -19,7 +19,7 @@
--
-- Definition of representational equality ('Coercion').
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
-----------------------------------------------------------------------------
module Data.Type.Coercion
......@@ -44,7 +44,7 @@ import GHC.Base
-- To use this equality in practice, pattern-match on the @Coercion a b@ to get out
-- the @Coercible a b@ instance, and then use 'coerce' to apply it.
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
data Coercion a b where
Coercion :: Coercible a b => Coercion a b
......
......@@ -23,7 +23,7 @@
-- Definition of propositional equality @(:~:)@. Pattern-matching on a variable
-- of type @(a :~: b)@ produces a proof that @a ~ b@.
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
-----------------------------------------------------------------------------
......@@ -56,7 +56,7 @@ infix 4 :~:
-- in practice, pattern-match on the @a :~: b@ to get out the @Refl@ constructor;
-- in the body of the pattern-match, the compiler knows that @a ~ b@.
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
data a :~: b where
Refl :: a :~: a
......
......@@ -104,7 +104,7 @@ cast x = if typeRep (Proxy :: Proxy a) == typeRep (Proxy :: Proxy b)
-- | Extract a witness of equality of two types
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
eqT :: forall a b. (Typeable a, Typeable b) => Maybe (a :~: b)
eqT = if typeRep (Proxy :: Proxy a) == typeRep (Proxy :: Proxy b)
then Just $ unsafeCoerce Refl
......
......@@ -94,9 +94,9 @@ instance Ord TypeRep where
-- be built using 'mkTyCon'.
data TyCon = TyCon {
tyConHash :: {-# UNPACK #-} !Fingerprint,
tyConPackage :: String, -- ^ /Since: 4.5.0.0/
tyConModule :: String, -- ^ /Since: 4.5.0.0/
tyConName :: String -- ^ /Since: 4.5.0.0/
tyConPackage :: String, -- ^ @since 4.5.0.0
tyConModule :: String, -- ^ @since 4.5.0.0
tyConName :: String -- ^ @since 4.5.0.0
}
instance Eq TyCon where
......@@ -205,7 +205,7 @@ class Typeable a where
-- | Takes a value of type @a@ and returns a concrete representation
-- of that type.
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
typeRep :: forall proxy a. Typeable a => proxy a -> TypeRep
typeRep _ = typeRep# (proxy# :: Proxy# a)
{-# INLINE typeRep #-}
......
......@@ -17,7 +17,7 @@
-- A logically uninhabited data type, used to indicate that a given
-- term should not exist.
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
----------------------------------------------------------------------------
module Data.Void
( Void
......@@ -32,7 +32,7 @@ import GHC.Generics
-- | Uninhabited data type
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
data Void deriving (Generic)
deriving instance Data Void
......@@ -62,13 +62,13 @@ instance Exception Void
-- | Since 'Void' values logically don't exist, this witnesses the
-- logical reasoning tool of \"ex falso quodlibet\".
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
absurd :: Void -> a
absurd a = case a of {}
-- | If 'Void' is uninhabited then any 'Functor' that holds only
-- values of type 'Void' is holding no values.
--
-- /Since: 4.8.0.0/
-- @since 4.8.0.0
vacuous :: Functor f => f Void -> f a
vacuous = fmap absurd
......@@ -69,7 +69,7 @@ import Data.List
-- | The 'traceIO' function outputs the trace message from the IO monad.
-- This sequences the output with respect to other IO actions.
--
-- /Since: 4.5.0.0/
-- @since 4.5.0.0
traceIO :: String -> IO ()
traceIO msg = do
withCString "%s\n" $ \cfmt -> do
......@@ -115,7 +115,7 @@ trace string expr = unsafePerformIO $ do
{-|
Like 'trace' but returns the message instead of a third value.
/Since: 4.7.0.0/
@since 4.7.0.0
-}
traceId :: String -> String
traceId a = trace a a
......@@ -139,7 +139,7 @@ traceShow = trace . show
{-|
Like 'traceShow' but returns the shown value instead of a third value.
/Since: 4.7.0.0/
@since 4.7.0.0
-}
traceShowId :: (Show a) => a -> a
traceShowId a = trace (show a) a
......@@ -155,7 +155,7 @@ monad, as 'traceIO' is in the 'IO' monad.
> y <- ...
> traceM $ "y: " ++ show y
/Since: 4.7.0.0/
@since 4.7.0.0
-}
traceM :: (Monad m) => String -> m ()
traceM string = trace string $ return ()
......@@ -169,7 +169,7 @@ Like 'traceM', but uses 'show' on the argument to convert it to a 'String'.
> y <- ...
> traceMShow $ x + y
/Since: 4.7.0.0/
@since 4.7.0.0
-}
traceShowM :: (Show a, Monad m) => a -> m ()
traceShowM = traceM . show
......@@ -183,7 +183,7 @@ traceShowM = traceM . show
-- stack correspond to @SCC@ annotations, so it is a good idea to use
-- @-fprof-auto@ or @-fprof-auto-calls@ to add SCC annotations automatically.
--
-- /Since: 4.5.0.0/
-- @since 4.5.0.0
traceStack :: String -> a -> a
traceStack str expr = unsafePerformIO $ do
traceIO str
......@@ -216,7 +216,7 @@ traceStack str expr = unsafePerformIO $ do
-- duplicate events emitted if two CPUs simultaneously evaluate the same thunk
-- that uses 'traceEvent'.
--
-- /Since: 4.5.0.0/
-- @since 4.5.0.0
traceEvent :: String -> a -> a
traceEvent msg expr = unsafeDupablePerformIO $ do
traceEventIO msg
......@@ -228,7 +228,7 @@ traceEvent msg expr = unsafeDupablePerformIO $ do
-- Compared to 'traceEvent', 'traceEventIO' sequences the event with respect to
-- other IO actions.
--
-- /Since: 4.5.0.0/
-- @since 4.5.0.0
traceEventIO :: String -> IO ()
traceEventIO msg =
GHC.Foreign.withCString utf8 msg $ \(Ptr p) -> IO $ \s ->
......@@ -266,7 +266,7 @@ traceEventIO msg =
-- duplicate events emitted if two CPUs simultaneously evaluate the same thunk
-- that uses 'traceMarker'.
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
traceMarker :: String -> a -> a
traceMarker msg expr = unsafeDupablePerformIO $ do
traceMarkerIO msg
......@@ -278,7 +278,7 @@ traceMarker msg expr = unsafeDupablePerformIO $ do
-- Compared to 'traceMarker', 'traceMarkerIO' sequences the event with respect to
-- other IO actions.
--
-- /Since: 4.7.0.0/
-- @since 4.7.0.0
traceMarkerIO :: String -> IO ()
traceMarkerIO msg =
GHC.Foreign.withCString utf8 msg $ \(Ptr p) -> IO $ \s ->
......
......@@ -204,7 +204,7 @@ eNOTDIR = Errno (CONST_ENOTDIR)
eNOTEMPTY = Errno (CONST_ENOTEMPTY)