Commit ddffa0cd authored by Alec Theriault's avatar Alec Theriault Committed by Ben Gamari

Fix ambiguous/out-of-scope Haddock identifiers

This drastically cuts down on the number of Haddock warnings when making
docs for `base`.  Plus this means more actual links end up in the docs!
Also fixed other small mostly markup issues in the documentation along
the way.

This is a docs-only change.

Reviewers: hvr, bgamari, thomie

Reviewed By: thomie

Subscribers: thomie, rwbarton, carter

Differential Revision: https://phabricator.haskell.org/D5055
parent 14817621
......@@ -76,7 +76,7 @@ infixr 1 ^<<, <<^
--
-- * @'first' f >>> 'arr' ('id' *** g) = 'arr' ('id' *** g) >>> 'first' f@
--
-- * @'first' ('first' f) >>> 'arr' 'assoc' = 'arr' 'assoc' >>> 'first' f@
-- * @'first' ('first' f) >>> 'arr' assoc = 'arr' assoc >>> 'first' f@
--
-- where
--
......@@ -209,7 +209,7 @@ instance MonadPlus m => ArrowPlus (Kleisli m) where
--
-- * @'left' f >>> 'arr' ('id' +++ g) = 'arr' ('id' +++ g) >>> 'left' f@
--
-- * @'left' ('left' f) >>> 'arr' 'assocsum' = 'arr' 'assocsum' >>> 'left' f@
-- * @'left' ('left' f) >>> 'arr' assocsum = 'arr' assocsum >>> 'left' f@
--
-- where
--
......
......@@ -102,8 +102,8 @@ writeChan (Chan _ writeVar) val = do
-- guarantees of 'MVar's (e.g. threads blocked in this operation are woken up in
-- FIFO order).
--
-- Throws 'BlockedIndefinitelyOnMVar' when the channel is empty and no other
-- thread holds a reference to the channel.
-- Throws 'Control.Exception.BlockedIndefinitelyOnMVar' when the channel is
-- empty and no other thread holds a reference to the channel.
readChan :: Chan a -> IO a
readChan (Chan readVar _) = do
modifyMVar readVar $ \read_end -> do
......
......@@ -33,12 +33,12 @@
--
-- === Applicability
--
-- 'MVar's offer more flexibility than 'IORef's, but less flexibility
-- than 'STM'. They are appropriate for building synchronization
-- 'MVar's offer more flexibility than 'Data.IORef.IORef's, but less flexibility
-- than 'GHC.Conc.STM'. They are appropriate for building synchronization
-- primitives and performing simple interthread communication; however
-- they are very simple and susceptible to race conditions, deadlocks or
-- uncaught exceptions. Do not use them if you need perform larger
-- atomic operations such as reading from multiple variables: use 'GHC.Conc.STM'
-- instead.
--
-- In particular, the "bigger" functions in this module ('swapMVar',
......@@ -70,7 +70,7 @@
--
-- 'MVar' operations are always observed to take place in the order
-- they are written in the program, regardless of the memory model of
-- the underlying machine. This is in contrast to 'IORef' operations
-- the underlying machine. This is in contrast to 'Data.IORef.IORef' operations
-- which may appear out-of-order to another thread in some cases.
--
-- === Example
......
......@@ -264,7 +264,7 @@ to write something like
> (\e -> handler)
If you need to unmask asynchronous exceptions again in the exception
handler, 'restore' can be used there too.
handler, @restore@ can be used there too.
Note that 'try' and friends /do not/ have a similar default, because
there is no exception handler in this case. Don't use 'try' for
......@@ -332,21 +332,24 @@ kind of situation:
The following operations are guaranteed not to be interruptible:
* operations on 'IORef' from "Data.IORef"
* operations on 'Data.IORef.IORef' from "Data.IORef"
* STM transactions that do not use 'retry'
* STM transactions that do not use 'GHC.Conc.retry'
* everything from the @Foreign@ modules
* everything from @Control.Exception@ except for 'throwTo'
* everything from "Control.Exception" except for 'throwTo'
* @tryTakeMVar@, @tryPutMVar@, @isEmptyMVar@
* 'Control.Concurrent.MVar.tryTakeMVar', 'Control.Concurrent.MVar.tryPutMVar',
'Control.Concurrent.MVar.isEmptyMVar'
* @takeMVar@ if the @MVar@ is definitely full, and conversely @putMVar@ if the @MVar@ is definitely empty
* 'Control.Concurrent.MVar.takeMVar' if the 'Control.Concurrent.MVar.MVar' is
definitely full, and conversely 'Control.Concurrent.MVar.putMVar' if the
'Control.Concurrent.MVar.MVar' is definitely empty
* @newEmptyMVar@, @newMVar@
* 'Control.Concurrent.MVar.newEmptyMVar', 'Control.Concurrent.MVar.newMVar'
* @forkIO@, @forkIOUnmasked@, @myThreadId@
* 'Control.Concurrent.forkIO', 'Control.Concurrent.myThreadId'
-}
......
......@@ -131,7 +131,7 @@ guard :: (Alternative f) => Bool -> f ()
guard True = pure ()
guard False = empty
-- | This generalizes the list-based 'filter' function.
-- | This generalizes the list-based 'Data.List.filter' function.
{-# INLINE filterM #-}
filterM :: (Applicative m) => (a -> m Bool) -> [a] -> m [a]
......@@ -203,7 +203,7 @@ zipWithM_ :: (Applicative m) => (a -> b -> m c) -> [a] -> [b] -> m ()
{-# INLINE zipWithM_ #-}
zipWithM_ f xs ys = sequenceA_ (zipWith f xs ys)
{- | The 'foldM' function is analogous to 'foldl', except that its result is
{- | The 'foldM' function is analogous to 'Data.Foldable.foldl', except that its result is
encapsulated in a monad. Note that 'foldM' works from left-to-right over
the list arguments. This could be an issue where @('>>')@ and the `folded
function' are not commutative.
......
......@@ -50,13 +50,13 @@ import {-# SOURCE #-} GHC.IO (failIO)
-- only a single data constructor, and irrefutable patterns (@~pat@).
--
-- Instances of 'MonadFail' should satisfy the following law: @fail s@ should
-- be a left zero for '>>=',
-- be a left zero for 'Control.Monad.>>=',
--
-- @
-- fail s >>= f = fail s
-- @
--
-- If your 'Monad' is also 'MonadPlus', a popular definition is
-- If your 'Monad' is also 'Control.Monad.MonadPlus', a popular definition is
--
-- @
-- fail _ = mzero
......
......@@ -40,7 +40,7 @@ import System.IO
-- Instances of 'MonadFix' should satisfy the following laws:
--
-- [/purity/]
-- @'mfix' ('return' . h) = 'return' ('fix' h)@
-- @'mfix' ('Control.Monad.return' . h) = 'Control.Monad.return' ('fix' h)@
--
-- [/left shrinking/ (or /tightening/)]
-- @'mfix' (\\x -> a >>= \\y -> f x y) = a >>= \\y -> 'mfix' (\\x -> f x y)@
......
......@@ -24,7 +24,7 @@ module Control.Monad.ST.Imp (
runST,
fixST,
-- * Converting 'ST' to 'IO'
-- * Converting 'ST' to 'Prelude.IO'
RealWorld, -- abstract
stToIO,
......
......@@ -76,7 +76,7 @@ import GHC.Generics (K1(..))
-- 'bifoldr' f g z t ≡ 'appEndo' ('bifoldMap' (Endo . f) (Endo . g) t) z
-- @
--
-- If the type is also a 'Bifunctor' instance, it should satisfy:
-- If the type is also a 'Data.Bifunctor.Bifunctor' instance, it should satisfy:
--
-- > 'bifoldMap' f g ≡ 'bifold' . 'bimap' f g
--
......
......@@ -52,8 +52,11 @@ import GHC.Generics (K1(..))
-- @'bitraverse' 'Identity' 'Identity' ≡ 'Identity'@
--
-- [/composition/]
-- @'Compose' . 'fmap' ('bitraverse' g1 g2) . 'bitraverse' f1 f2
-- ≡ 'traverse' ('Compose' . 'fmap' g1 . f1) ('Compose' . 'fmap' g2 . f2)@
-- @'Data.Functor.Compose.Compose' .
-- 'fmap' ('bitraverse' g1 g2) .
-- 'bitraverse' f1 f2
-- ≡ 'traverse' ('Data.Functor.Compose.Compose' . 'fmap' g1 . f1)
-- ('Data.Functor.Compose.Compose' . 'fmap' g2 . f2)@
--
-- where an /applicative transformation/ is a function
--
......@@ -66,26 +69,9 @@ import GHC.Generics (K1(..))
-- t (f '<*>' x) = t f '<*>' t x
-- @
--
-- and the identity functor 'Identity' and composition functors 'Compose' are
-- defined as
--
-- > newtype Identity a = Identity { runIdentity :: a }
-- >
-- > instance Functor Identity where
-- > fmap f (Identity x) = Identity (f x)
-- >
-- > instance Applicative Identity where
-- > pure = Identity
-- > Identity f <*> Identity x = Identity (f x)
-- >
-- > newtype Compose f g a = Compose (f (g a))
-- >
-- > instance (Functor f, Functor g) => Functor (Compose f g) where
-- > fmap f (Compose x) = Compose (fmap (fmap f) x)
-- >
-- > instance (Applicative f, Applicative g) => Applicative (Compose f g) where
-- > pure = Compose . pure . pure
-- and the identity functor 'Identity' and composition functors
-- 'Data.Functor.Compose.Compose' are from "Data.Functor.Identity" and
-- "Data.Functor.Compose".
--
-- Some simple examples are 'Either' and '(,)':
--
......
......@@ -164,7 +164,7 @@ instance Monad (Either e) where
--
-- We create two values of type @'Either' 'String' 'Int'@, one using the
-- 'Left' constructor and another using the 'Right' constructor. Then
-- we apply \"either\" the 'length' function (if we have a 'String')
-- we apply \"either\" the 'Prelude.length' function (if we have a 'String')
-- or the \"times-two\" function (if we have an 'Int'):
--
-- >>> let s = Left "foo" :: Either String Int
......
......@@ -172,8 +172,8 @@ class Foldable t where
--
-- Also note that if you want an efficient left-fold, you probably want to
-- use 'foldl'' instead of 'foldl'. The reason for this is that latter does
-- not force the "inner" results (e.g. @z `f` x1@ in the above example)
-- before applying them to the operator (e.g. to @(`f` x2)@). This results
-- not force the "inner" results (e.g. @z \`f\` x1@ in the above example)
-- before applying them to the operator (e.g. to @(\`f\` x2)@). This results
-- in a thunk chain @O(n)@ elements long, which then must be evaluated from
-- the outside-in.
--
......
......@@ -45,16 +45,18 @@ infixl 1 &
-- 120
--
-- Instead of making a recursive call, we introduce a dummy parameter @rec@;
-- when used within 'fix', this parameter then refers to 'fix'' argument, hence
-- when used within 'fix', this parameter then refers to 'fix' argument, hence
-- the recursion is reintroduced.
fix :: (a -> a) -> a
fix f = let x = f x in x
-- | @'on' b u x y@ runs the binary function `b` /on/ the results of applying unary function `u` to two arguments `x` and `y`. From the opposite perspective, it transforms two inputs and combines the outputs.
-- | @'on' b u x y@ runs the binary function @b@ /on/ the results of applying
-- unary function @u@ to two arguments @x@ and @y@. From the opposite
-- perspective, it transforms two inputs and combines the outputs.
--
-- @((+) \``on`\` f) x y = f x + f y@
--
-- Typical usage: @'Data.List.sortBy' ('compare' \`on\` 'fst')@.
-- Typical usage: @'Data.List.sortBy' ('Prelude.compare' \`on\` 'Prelude.fst')@.
--
-- Algebraic properties:
--
......
......@@ -57,26 +57,27 @@ infixl 4 <$>
-- | An infix synonym for 'fmap'.
--
-- The name of this operator is an allusion to '$'.
-- The name of this operator is an allusion to 'Prelude.$'.
-- Note the similarities between their types:
--
-- > ($) :: (a -> b) -> a -> b
-- > (<$>) :: Functor f => (a -> b) -> f a -> f b
--
-- Whereas '$' is function application, '<$>' is function
-- Whereas 'Prelude.$' is function application, '<$>' is function
-- application lifted over a 'Functor'.
--
-- ==== __Examples__
--
-- Convert from a @'Maybe' 'Int'@ to a @'Maybe' 'String'@ using 'show':
-- Convert from a @'Data.Maybe.Maybe' 'Data.Int.Int'@ to a @'Data.Maybe.Maybe'
-- 'Data.String.String'@ using 'Prelude.show':
--
-- >>> show <$> Nothing
-- Nothing
-- >>> show <$> Just 3
-- Just "3"
--
-- Convert from an @'Either' 'Int' 'Int'@ to an @'Either' 'Int'@
-- 'String' using 'show':
-- Convert from an @'Data.Either.Either' 'Data.Int.Int' 'Data.Int.Int'@ to an
-- @'Data.Either.Either' 'Data.Int.Int'@ 'Data.String.String' using 'Prelude.show':
--
-- >>> show <$> Left 17
-- Left 17
......@@ -88,7 +89,7 @@ infixl 4 <$>
-- >>> (*2) <$> [1,2,3]
-- [2,4,6]
--
-- Apply 'even' to the second element of a pair:
-- Apply 'Prelude.even' to the second element of a pair:
--
-- >>> even <$> (2,2)
-- (2,True)
......@@ -129,27 +130,29 @@ infixl 1 <&>
--
-- ==== __Examples__
--
-- Replace the contents of a @'Maybe' 'Int'@ with a constant 'String':
-- Replace the contents of a @'Data.Maybe.Maybe' 'Data.Int.Int'@ with a constant
-- 'Data.String.String':
--
-- >>> Nothing $> "foo"
-- Nothing
-- >>> Just 90210 $> "foo"
-- Just "foo"
--
-- Replace the contents of an @'Either' 'Int' 'Int'@ with a constant
-- 'String', resulting in an @'Either' 'Int' 'String'@:
-- Replace the contents of an @'Data.Either.Either' 'Data.Int.Int' 'Data.Int.Int'@
-- with a constant 'Data.String.String', resulting in an @'Data.Either.Either'
-- 'Data.Int.Int' 'Data.String.String'@:
--
-- >>> Left 8675309 $> "foo"
-- Left 8675309
-- >>> Right 8675309 $> "foo"
-- Right "foo"
--
-- Replace each element of a list with a constant 'String':
-- Replace each element of a list with a constant 'Data.String.String':
--
-- >>> [1,2,3] $> "foo"
-- ["foo","foo","foo"]
--
-- Replace the second element of a pair with a constant 'String':
-- Replace the second element of a pair with a constant 'Data.String.String':
--
-- >>> (1,2) $> "foo"
-- (1,"foo")
......@@ -162,15 +165,15 @@ infixl 1 <&>
--
-- ==== __Examples__
--
-- Replace the contents of a @'Maybe' 'Int'@ with unit:
-- Replace the contents of a @'Data.Maybe.Maybe' 'Data.Int.Int'@ with unit:
--
-- >>> void Nothing
-- Nothing
-- >>> void (Just 3)
-- Just ()
--
-- Replace the contents of an @'Either' 'Int' 'Int'@ with unit,
-- resulting in an @'Either' 'Int' '()'@:
-- Replace the contents of an @'Data.Either.Either' 'Data.Int.Int' 'Data.Int.Int'@
-- with unit, resulting in an @'Data.Either.Either' 'Data.Int.Int' '()'@:
--
-- >>> void (Left 8675309)
-- Left 8675309
......
......@@ -59,7 +59,7 @@ newtype Const a b = Const { getConst :: a }
)
-- | This instance would be equivalent to the derived instances of the
-- 'Const' newtype if the 'runConst' field were removed
-- 'Const' newtype if the 'getConst' field were removed
--
-- @since 4.8.0.0
instance Read a => Read (Const a b) where
......@@ -67,7 +67,7 @@ instance Read a => Read (Const a b) where
$ \r -> [(Const x,t) | ("Const", s) <- lex r, (x, t) <- readsPrec 11 s]
-- | This instance would be equivalent to the derived instances of the
-- 'Const' newtype if the 'runConst' field were removed
-- 'Const' newtype if the 'getConst' field were removed
--
-- @since 4.8.0.0
instance Show a => Show (Const a b) where
......
......@@ -103,7 +103,7 @@ class Contravariant f where
(>$) :: b -> f b -> f a
(>$) = contramap . const
-- | If 'f' is both 'Functor' and 'Contravariant' then by the time you factor
-- | If @f@ is both 'Functor' and 'Contravariant' then by the time you factor
-- in the laws of each of those classes, it can't actually use its argument in
-- any meaningful capacity.
--
......
......@@ -178,8 +178,8 @@ module Data.List
-- counterpart whose name is suffixed with \`@By@\'.
--
-- It is often convenient to use these functions together with
-- 'Data.Function.on', for instance @'sortBy' ('compare'
-- \`on\` 'fst')@.
-- 'Data.Function.on', for instance @'sortBy' ('Prelude.compare'
-- ``Data.Function.on`` 'Prelude.fst')@.
-- *** User-supplied equality (replacing an @Eq@ context)
-- | The predicate is assumed to define an equivalence.
......
......@@ -380,7 +380,7 @@ groupWith1 f = groupBy1 ((==) `on` f)
groupAllWith1 :: (Ord b) => (a -> b) -> NonEmpty a -> NonEmpty (NonEmpty a)
groupAllWith1 f = groupWith1 f . sortWith f
-- | The 'isPrefix' function returns @True@ if the first argument is
-- | The 'isPrefixOf' function returns 'True' if the first argument is
-- a prefix of the second.
isPrefixOf :: Eq a => [a] -> NonEmpty a -> Bool
isPrefixOf [] _ = True
......
......@@ -55,7 +55,7 @@ import GHC.Base
-- >>> maybe False odd Nothing
-- False
--
-- Read an integer from a string using 'readMaybe'. If we succeed,
-- Read an integer from a string using 'Text.Read.readMaybe'. If we succeed,
-- return twice the integer; that is, apply @(*2)@ to it. If instead
-- we fail to parse an integer, return @0@ by default:
--
......@@ -65,7 +65,7 @@ import GHC.Base
-- >>> maybe 0 (*2) (readMaybe "")
-- 0
--
-- Apply 'show' to a @Maybe Int@. If we have @Just n@, we want to show
-- Apply 'Prelude.show' to a @Maybe Int@. If we have @Just n@, we want to show
-- the underlying 'Int' @n@. But if we have 'Nothing', we return the
-- empty string instead of (for example) \"Nothing\":
--
......@@ -161,7 +161,7 @@ fromJust (Just x) = x
-- >>> fromMaybe "" Nothing
-- ""
--
-- Read an integer from a string using 'readMaybe'. If we fail to
-- Read an integer from a string using 'Text.Read.readMaybe'. If we fail to
-- parse an integer, we want to return @0@ by default:
--
-- >>> import Text.Read ( readMaybe )
......
......@@ -91,7 +91,7 @@ import Control.Monad.Fail (MonadFail)
import Data.Semigroup.Internal
-- $MaybeExamples
-- To implement @find@ or @findLast@ on any 'Foldable':
-- To implement @find@ or @findLast@ on any 'Data.Foldable.Foldable':
--
-- @
-- findLast :: Foldable t => (a -> Bool) -> t a -> Maybe a
......@@ -100,20 +100,20 @@ import Data.Semigroup.Internal
-- else Last Nothing)
-- @
--
-- Much of Data.Map's interface can be implemented with
-- Data.Map.alter. Some of the rest can be implemented with a new
-- @alterA@ function and either 'First' or 'Last':
-- Much of 'Data.Map.Lazy.Map's interface can be implemented with
-- 'Data.Map.Lazy.alter'. Some of the rest can be implemented with a new
-- 'Data.Map.Lazy.alterF' function and either 'First' or 'Last':
--
-- > alterA :: (Applicative f, Ord k) =>
-- > alterF :: (Functor f, Ord k) =>
-- > (Maybe a -> f (Maybe a)) -> k -> Map k a -> f (Map k a)
-- >
-- > instance Monoid a => Applicative ((,) a) -- from Control.Applicative
-- > instance Monoid a => Functor ((,) a) -- from Data.Functor
--
-- @
-- insertLookupWithKey :: Ord k => (k -> v -> v -> v) -> k -> v
-- -> Map k v -> (Maybe v, Map k v)
-- insertLookupWithKey combine key value =
-- Arrow.first getFirst . alterA doChange key
-- Arrow.first getFirst . 'Data.Map.Lazy.alterF' doChange key
-- where
-- doChange Nothing = (First Nothing, Just value)
-- doChange (Just oldValue) =
......
......@@ -380,14 +380,14 @@ forM :: (Traversable t, Monad m) => t a -> (a -> m b) -> m (t b)
forM = flip mapM
-- |The 'mapAccumL' function behaves like a combination of 'fmap'
-- and 'Data.Foldable.foldl'; it applies a function to each element of a structure,
-- passing an accumulating parameter from left to right, and returning
-- a final value of this accumulator together with the new structure.
mapAccumL :: Traversable t => (a -> b -> (a, c)) -> a -> t b -> (a, t c)
mapAccumL f s t = runStateL (traverse (StateL . flip f) t) s
-- |The 'mapAccumR' function behaves like a combination of 'fmap'
-- and 'Data.Foldable.foldr'; it applies a function to each element of a structure,
-- passing an accumulating parameter from right to left, and returning
-- a final value of this accumulator together with the new structure.
mapAccumR :: Traversable t => (a -> b -> (a, c)) -> a -> t b -> (a, t c)
......
......@@ -169,8 +169,9 @@ Note that the application of 'traceM' is not an action in the 'Applicative'
context, as 'traceIO' is in the 'IO' type. While the fresh bindings in the
following example will force the 'traceM' expressions to be reduced every time
the @do@-block is executed, @traceM "not crashed"@ would only be reduced once,
and the message would only be printed once. If your monad is in 'MonadIO',
@liftIO . traceIO@ may be a better option.
and the message would only be printed once. If your monad is in
'Control.Monad.IO.Class.MonadIO', @'Control.Monad.IO.Class.liftIO' . 'traceIO'@
may be a better option.
>>> :{
do
......
......@@ -37,9 +37,9 @@ module Foreign.C.Types
-- | These types are represented as @newtype@s of
-- types in "Data.Int" and "Data.Word", and are instances of
-- 'Prelude.Eq', 'Prelude.Ord', 'Prelude.Num', 'Prelude.Read',
-- 'Prelude.Show', 'Prelude.Enum', 'Typeable', 'Storable',
-- 'Prelude.Bounded', 'Prelude.Real', 'Prelude.Integral' and
-- 'Bits'.
-- 'Prelude.Show', 'Prelude.Enum', 'Data.Typeable.Typeable',
-- 'Storable', 'Prelude.Bounded', 'Prelude.Real', 'Prelude.Integral'
-- and 'Bits'.
CChar(..), CSChar(..), CUChar(..)
, CShort(..), CUShort(..), CInt(..), CUInt(..)
, CLong(..), CULong(..)
......@@ -51,7 +51,8 @@ module Foreign.C.Types
-- | These types are represented as @newtype@s of basic
-- foreign types, and are instances of
-- 'Prelude.Eq', 'Prelude.Ord', 'Prelude.Num', 'Prelude.Read',
-- 'Prelude.Show', 'Prelude.Enum', 'Typeable' and 'Storable'.
-- 'Prelude.Show', 'Prelude.Enum', 'Data.Typeable.Typeable' and
-- 'Storable'.
, CClock(..), CTime(..), CUSeconds(..), CSUSeconds(..)
-- extracted from CTime, because we don't want this comment in
......@@ -66,7 +67,7 @@ module Foreign.C.Types
-- | These types are represented as @newtype@s of
-- 'Prelude.Float' and 'Prelude.Double', and are instances of
-- 'Prelude.Eq', 'Prelude.Ord', 'Prelude.Num', 'Prelude.Read',
-- 'Prelude.Show', 'Prelude.Enum', 'Typeable', 'Storable',
-- 'Prelude.Show', 'Prelude.Enum', 'Data.Typeable.Typeable', 'Storable',
-- 'Prelude.Real', 'Prelude.Fractional', 'Prelude.Floating',
-- 'Prelude.RealFrac' and 'Prelude.RealFloat'. That does mean
-- that `CFloat`'s (respectively `CDouble`'s) instances of
......
......@@ -40,33 +40,34 @@ newForeignPtr :: Ptr a -> IO () -> IO (ForeignPtr a)
-- associating a finalizer - given by the monadic operation - with the
-- reference. The storage manager will start the finalizer, in a
-- separate thread, some time after the last reference to the
-- @ForeignPtr@ is dropped. There is no guarantee of promptness, and
-- 'ForeignPtr' is dropped. There is no guarantee of promptness, and
-- in fact there is no guarantee that the finalizer will eventually
-- run at all.
--
-- Note that references from a finalizer do not necessarily prevent
-- another object from being finalized. If A's finalizer refers to B
-- (perhaps using 'touchForeignPtr', then the only guarantee is that
-- B's finalizer will never be started before A's. If both A and B
-- are unreachable, then both finalizers will start together. See
-- 'touchForeignPtr' for more on finalizer ordering.
-- (perhaps using 'Foreign.ForeignPtr.touchForeignPtr', then the only
-- guarantee is that B's finalizer will never be started before A's. If both
-- A and B are unreachable, then both finalizers will start together. See
-- 'Foreign.ForeignPtr.touchForeignPtr' for more on finalizer ordering.
--
newForeignPtr = GHC.ForeignPtr.newConcForeignPtr
addForeignPtrFinalizer :: ForeignPtr a -> IO () -> IO ()
-- ^This function adds a finalizer to the given @ForeignPtr@. The
-- ^This function adds a finalizer to the given 'ForeignPtr'. The
-- finalizer will run /before/ all other finalizers for the same
-- object which have already been registered.
--
-- This is a variant of @Foreign.ForeignPtr.addForeignPtrFinalizer@,
-- where the finalizer is an arbitrary @IO@ action. When it is
-- This is a variant of 'Foreign.ForeignPtr.addForeignPtrFinalizer',
-- where the finalizer is an arbitrary 'IO' action. When it is
-- invoked, the finalizer will run in a new thread.
--
-- NB. Be very careful with these finalizers. One common trap is that
-- if a finalizer references another finalized value, it does not
-- prevent that value from being finalized. In particular, 'Handle's
-- are finalized objects, so a finalizer should not refer to a 'Handle'
-- (including @stdout@, @stdin@ or @stderr@).
-- prevent that value from being finalized. In particular, 'System.IO.Handle's
-- are finalized objects, so a finalizer should not refer to a
-- 'System.IO.Handle' (including 'System.IO.stdout', 'System.IO.stdin', or
-- 'System.IO.stderr').
--
addForeignPtrFinalizer = GHC.ForeignPtr.addForeignPtrConcFinalizer
......@@ -453,13 +453,13 @@ array :: Ix i
-- of the array. These bounds are the lowest and
-- highest indices in the array, in that order.
-- For example, a one-origin vector of length
-- '10' has bounds '(1,10)', and a one-origin '10'
-- by '10' matrix has bounds '((1,1),(10,10))'.
-- @10@ has bounds @(1,10)@, and a one-origin @10@
-- by @10@ matrix has bounds @((1,1),(10,10))@.
-> [(i, e)] -- ^ a list of /associations/ of the form
-- (/index/, /value/). Typically, this list will
-- be expressed as a comprehension. An
-- association '(i, x)' defines the value of
-- the array at index 'i' to be 'x'.
-- association @(i, x)@ defines the value of
-- the array at index @i@ to be @x@.
-> Array i e
array (l,u) ies
= let n = safeRangeSize (l,u)
......
......@@ -222,7 +222,7 @@ class Semigroup a where
-- | An associative operation.
(<>) :: a -> a -> a
-- | Reduce a non-empty list with @\<\>@
-- | Reduce a non-empty list with '<>'
--
-- The default definition should be sufficient, but this can be
-- overridden for efficiency.
......@@ -240,7 +240,7 @@ class Semigroup a where
--
-- By making this a member of the class, idempotent semigroups
-- and monoids can upgrade this to execute in /O(1)/ by
-- picking @stimes = 'stimesIdempotent'@ or @stimes =
-- picking @stimes = 'Data.Semigroup.stimesIdempotent'@ or @stimes =
-- 'stimesIdempotentMonoid'@ respectively.
stimes :: Integral b => b -> a -> a
stimes = stimesDefault
......@@ -255,7 +255,7 @@ class Semigroup a where
--
-- * @x '<>' (y '<>' z) = (x '<>' y) '<>' z@ ('Semigroup' law)
--
-- * @'mconcat' = 'foldr' '(<>)' 'mempty'@
-- * @'mconcat' = 'foldr' ('<>') 'mempty'@
--
-- The method names refer to the monoid of lists under concatenation,
-- but there are many other instances.
......@@ -263,7 +263,7 @@ class Semigroup a where
-- Some types can be viewed as a monoid in more than one way,
-- e.g. both addition and multiplication on numbers.
-- In such cases we often define @newtype@s and make those instances
-- of 'Monoid', e.g. 'Sum' and 'Product'.
-- of 'Monoid', e.g. 'Data.Semigroup.Sum' and 'Data.Semigroup.Product'.
--
-- __NOTE__: 'Semigroup' is a superclass of 'Monoid' since /base-4.11.0.0/.
class Semigroup a => Monoid a where
......@@ -273,7 +273,7 @@ class Semigroup a => Monoid a where
-- | An associative operation
--
-- __NOTE__: This method is redundant and has the default
-- implementation @'mappend' = '(<>)'@ since /base-4.11.0.0/.
-- implementation @'mappend' = ('<>')@ since /base-4.11.0.0/.
mappend :: a -> a -> a
mappend = (<>)
{-# INLINE mappend #-}
......@@ -473,7 +473,7 @@ class Functor f where
--
-- @('<*>') = 'liftA2' 'id'@
--
-- @'liftA2' f x y = f '<$>' x '<*>' y@
-- @'liftA2' f x y = f 'Prelude.<$>' x '<*>' y@
--
-- Further, any definition must satisfy the following:
--
......@@ -669,8 +669,8 @@ class Applicative m => Monad m where
-- failure in a @do@ expression.
--
-- As part of the MonadFail proposal (MFP), this function is moved
-- to its own class 'MonadFail' (see "Control.Monad.Fail" for more
-- details). The definition here will be removed in a future
-- to its own class 'Control.Monad.MonadFail' (see "Control.Monad.Fail" for
-- more details). The definition here will be removed in a future
-- release.
fail :: String -> m a
fail s = errorWithoutStackTrace s
......@@ -867,7 +867,7 @@ infixl 3 <|>
-- If defined, 'some' and 'many' should be the least solutions
-- of the equations:
--
-- * @'some' v = (:) '<$>' v '<*>' 'many' v@
-- * @'some' v = (:) 'Prelude.<$>' v '<*>' 'many' v@
--
-- * @'many' v = 'some' v '<|>' 'pure' []@
class Applicative f => Alternative f where
......@@ -1254,8 +1254,8 @@ id x = x
-- The compiler may rewrite it to @('assertError' line)@.
-- | If the first argument evaluates to 'True', then the result is the
-- second argument. Otherwise an 'AssertionFailed' exception is raised,
-- containing a 'String' with the source file and line number of the
-- second argument. Otherwise an 'Control.Exception.AssertionFailed' exception
-- is raised, containing a 'String' with the source file and line number of the
-- call to 'assert'.
--
-- Assertions can normally be turned on or off with a compiler flag
......@@ -1386,7 +1386,7 @@ unIO :: IO a -> (State# RealWorld -> (# State# RealWorld, a #))
unIO (IO a) = a
{- |
Returns the 'tag' of a constructor application; this function is used
Returns the tag of a constructor application; this function is used
by the deriving code for Eq, Ord and Enum.
The primitive dataToTag# requires an evaluated constructor application
......
......@@ -85,7 +85,7 @@ ioManagerCapabilitiesChanged = return ()
-- | Block the current thread until data is available to read on the
-- given file descriptor (GHC only).
--
-- This will throw an 'IOError' if the file descriptor was closed
-- This will throw an 'Prelude.IOError' if the file descriptor was closed
-- while this thread was blocked. To safely close a file descriptor
-- that has been used with 'threadWaitRead', use 'closeFdWith'.
threadWaitRead :: Fd -> IO ()
......@@ -101,7 +101,7 @@ threadWaitRead fd
-- | Block the current thread until data can be written to the
-- given file descriptor (GHC only).
--
-- This will throw an 'IOError' if the file descriptor was closed
-- This will throw an 'Prelude.IOError' if the file descriptor was closed
-- while this thread was blocked. To safely close a file descriptor
-- that has been used with 'threadWaitWrite', use 'closeFdWith'.
threadWaitWrite :: Fd -> IO ()
......
......@@ -543,8 +543,8 @@ data BlockReason
-- ^currently in a foreign call
| BlockedOnOther
-- ^blocked on some other resource. Without @-threaded@,
-- I\/O and 'threadDelay' show up as 'BlockedOnOther', with @-threaded@
-- they show up as 'BlockedOnMVar'.
-- I\/O and 'Control.Concurrent.threadDelay' show up as
-- 'BlockedOnOther', with @-threaded@ they show up as 'BlockedOnMVar'.
deriving ( Eq -- ^ @since 4.3.0.0
, Ord -- ^ @since 4.3.0.0
, Show -- ^ @since 4.3.0.0
......@@ -720,8 +720,11 @@ unsafeIOToSTM (IO m) = STM m
--
-- However, there are functions for creating transactional variables that
-- can always be safely called in 'unsafePerformIO'. See: 'newTVarIO',
-- 'newTChanIO', 'newBroadcastTChanIO', 'newTQueueIO', 'newTBQueueIO',
-- and 'newTMVarIO'.
-- 'Control.Concurrent.STM.TChan.newTChanIO',
-- 'Control.Concurrent.STM.TChan.newBroadcastTChanIO',
-- 'Control.Concurrent.STM.TQueue.newTQueueIO',
-- 'Control.Concurrent.STM.TBQueue.newTBQueueIO', and
-- 'Control.Concurrent.STM.TMVar.newTMVarIO'.
--
-- Using 'unsafePerformIO' inside of 'atomically' is also dangerous but for
-- different reasons. See 'unsafeIOToSTM' for more on this.
......
......@@ -21,10 +21,10 @@ import qualified GHC.Foreign as GHC
# endif
#endif